LDicomNet::Initialize

#include "ltdic.h"

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

L_CHAR *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:

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

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_CHAR *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_CHAR *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)
{
   LPCSTR pszMyPassword= "test";
   L_INT  nRet = 0;

   if ((L_INT)strlen(pszMyPassword) < nSize)
   {
      strcpy(pszPassword, pszMyPassword);
      nRet = strlen(pszMyPassword);
   }
   return nRet;
}

#ifndef CA_CERT_NAME
#define CA_CERT_NAME       "E:\\certificates\\CA.pem"
#endif

#ifndef SERVER_CERT_NAME
#define SERVER_CERT_NAME   "E:\\certificates\\Server.pem"
#endif

void CClDicomSamplesDlg::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("%s loaded successfully", SERVER_CERT_NAME);
         else
            csMsg.Format("%s could not be loaded successfully -- error[%d]", SERVER_CERT_NAME, nRet);
         AfxMessageBox(csMsg);
      }

      //
      // Use the CMyDicomNet object
      //

      // Cleanup
      delete pNet;
      LDicomNet::ShutDown();
   }
}