LDicomNet::Initialize

#include "ltdic.h"

L_INT LDicomNet::Initialize(pszPath, nMode, pCtxCreate)

L_TCHAR *pszPath;

/* character string */

L_UINT32 nMode;

/* initialization mode */

L_SSL_CTX_CREATE *pCtxCreate;

/* pointer to a structure */

This function is to be used in conjunction with the LDicomNet::LDicomNet(*pszPath, nMode, bReserved) constructor in order to change security options from the defaults. This function is available in the Medical Suite toolkits.

Parameter

Description

pszPath

Character string that contains the location of the temporary files. This should be the same string that was used in the LDicomNet constructor.

nMode

Flag that indicates the security mode to use when initializing the network structure. This should be the same flag that was used in the LDicomNet constructor. Possible values are:

 

Value

Meaning

 

DICOM_SECURE_NONE

No security mode.

 

DICOM_SECURE_ISCL

Integrated Secure Communication Layer security mode.

 

DICOM_SECURE_TLS

Transport Layer Security security mode.

pCtxCreate

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

Returns

SUCCESS

The function was successful.

> 0

An error occurred. Refer to Return Codes..

Comments

This function is to be used in conjunction with the LDicomNet::LDicomNet(*pszPath, nMode, bReserved) constructor when changing security options from the defaults. Note that when using the LDicomNet::LDicomNet(*pszPath, nMode, bReserved) version of the constructor, in addition to calling LDicomNet::Startup it is also necessary to call LDicomNet::Initialize in order to prepare the LDicomNet object for use. Use the pCtxCreate parameter when the nMode flag is set to DICOM_SECURE_TLS.

Note that the following uses of the LDicomNet constructors are functionally equivalent:

1.

LDicomNet *pNet = new LDicomNet(pszPath, nMode);

2.

LDicomNet *pNet = new LDicomNet(pszPath, nMode, 0);
If (pNet)
 pNet->Initialize(pszPath, nMode, NULL);

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

See Also

Functions:

LDicomNet::~LDicomNet, LDicomNet::StartUp, Class Members

Topics:

Adding TLS Security to a DICOM Connection

 

Negotiating a Ciphersuite

 

General Transport Layer Secure (TLS) Information

 

DICOM Network Connection: Creating a Network Connection

 

DICOM Connection: TLS Security

Example

// This sample creates a CMyDicomNet object with security

// The CMyDicomNet 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 CMyDicomNet object is assigned the certificate SERVER_CERT_NAME, which

// contains a password encrypted private key.

// The CMyDicomNet class implements the OnPrivateKeyPassword virtual function, which is

// used to supply the encryption password of the private key.

// Class CMyDicomNet

class CMyDicomNet : public LDicomNet  
   {
   public:
      CMyDicomNet(L_TCHAR *pszPath, L_INT32 nMode, L_BOOL bReserved);
      virtual ~CMyDicomNet();
      virtual L_INT  OnPrivateKeyPassword(L_CHAR *pszPassword, L_INT nSize, L_INT nFlag);
   };
CMyDicomNet::CMyDicomNet(L_TCHAR *pszPath, L_INT32 nMode, L_BOOL bReserved ) : LDicomNet(pszPath, nMode, bReserved)
{
}
CMyDicomNet::~CMyDicomNet()
   {
   }
L_INT CMyDicomNet::OnPrivateKeyPassword(L_CHAR *pszPassword, L_INT nSize, L_INT nFlag)
{
   UNREFERENCED_PARAMETER(nFlag);
   LPCSTR pszMyPassword= "test";
   L_INT nRet = 0;
   if ((L_INT)strlen(pszMyPassword) < nSize)
   {
      strcpy_s(pszPassword,4,pszMyPassword); 
      nRet = (L_INT)strlen(pszMyPassword);
   }
   return nRet;
}
#ifndef CA_CERT_NAME
#define CA_CERT_NAME      TEXT("E:\\certificates\\CA.pem")
#endif
#ifndef SERVER_CERT_NAME
#define SERVER_CERT_NAME  TEXT("E:\\certificates\\Server.pem")
#endif 
void OnButtonLdicomnet() 
   {
   L_INT nRet = DICOM_SUCCESS;
   LDicomNet::StartUp();
   CMyDicomNet *pNet = new CMyDicomNet(NULL, DICOM_SECURE_TLS, 0);
   if (pNet)
      {
      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;
      nRet = pNet->Initialize(NULL, DICOM_SECURE_TLS, &ctxCreate);
      if (nRet == DICOM_SUCCESS)
         {
         // Assign the server the certificate
         // Note that SERVER_CERT_NAME contains both the password and an ecnrypted private key
         // When loading the private key, the OnPrivateKeyPassword virtual function is called
         // so that the encryption password "test" can be supplied
         nRet = pNet->SetServerCertificateTLS (SERVER_CERT_NAME, L_TLS_FILETYPE_PEM, NULL);
         CString csMsg;
         if (nRet == DICOM_SUCCESS)
            csMsg.Format(TEXT("%s loaded successfully"), SERVER_CERT_NAME);
         else
            csMsg.Format(TEXT("%s could not be loaded successfully -- error[%d]"), SERVER_CERT_NAME, nRet);
         AfxMessageBox(csMsg);
         }
      //
      // Use the CMyDicomNet object 
      //
      // Cleanup
      delete pNet;
      LDicomNet::ShutDown();
      }
   }