LDicomNet::OnVerify

Summary

A callback that provides information during the certificate exchange/verification phase of TLS DICOM Security negotiation and optionally controls the verification process.

Syntax

virtual L_INT LDicomNet::OnVerify(ok, pszCertificateString, nError, pszErrorString)

Parameters

L_INT ok

An integer value that indicates the verification of the certificate was successful. Possible values are:

L_TCHAR *pszCertificateString

A character string that provides detailed information about the certificate.

L_INT nError

An Error Code that indicates success or an error.

L_TCHAR *pszErrorString

A friendly character string that corresponds to the nError parameter.

Returns

Comments

TLS Secure DICOM communications between an SCP and an SCU has a handshake process where the SCP and SCU verify each other’s provided certificates.

The LDicomNet::OnVerify callback is called once for each certificate in a certificate change, and provides information about the verification process.

This is useful for determining why a TLS DICOM Secure communication failed to be established.

The pszCertificateString provides information about a certificate, including:

• Subject Name
• Issuer Name
• Valid To Date
• Valid From Date
• Serial Number
• Basic Constraints (i.e. is this a Certificate Authority?)
• Certificate purposes list

For example, if an SCU is providing a certificate that is created without SSL Server and SSL Client purposes, the LDicomNet::OnVerify callback will be fired with an nError Error Code of L_X509_V_ERR_INVALID_PURPOSE(26), and show the problem in the Certificate Purposes section of the pszCertificateString.

An example pszCertificateString corresponding to a nError Error Code value of L_X509_V_ERR_INVALID_PURPOSE is shown below:

Subject Name: CN = Test Client, C = US, ST = Nebraska, L = Omaha, O = Test Client Organization 
Issuer Name: CN = LEAD CA, L = Charlotte, ST = North Carolina, C = US, emailAddress = support@leadtools.com, O = "LEAD Technologies, Inc." 
Valid From: Jun  1 21:31:35 2020 GMT 
Valid To: May 30 21:31:35 2030 GMT 
Serial Number:             ae:8a:75:37:56:03:c4:45 
Basic Constraints:Not a CA (Certificate Authority) 
Certificate purposes: 
   SSL client : No 
   SSL client CA : No 
   SSL server : No 
   SSL server CA : No 
   Netscape SSL server : No 
   Netscape SSL server CA : No 
   S/MIME signing : No 
   S/MIME signing CA : No 
   S/MIME encryption : No 
   S/MIME encryption CA : No 
   CRL signing : No 
   CRL signing CA : No 
   Any Purpose : Yes 
   Any Purpose CA : Yes 
   OCSP helper : Yes 
   OCSP helper CA : No 
   Time Stamp signing : No 

When overriding the LDicomNet::OnVerify callback, the return value of the override determines the verification behavior.

Return 0 to stop the verification process with a "verification failed" state. If LDicomNet::Initialize is called with an L_SSL_CTX_CREATE structure with L_SSL_VERIFY_PEER(0x01) set for the uVerifyMode, a verification failure alert is sent to the SCU and the TLS/SSL handshake is terminated.

Return 1 to continue the verification process. If LDicomNet::OnVerify always returns 1, the TLS/SSL handshake will not be terminated with respect to verification failures and the connection will be established.

Return ok to get the default verification behavior.

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

• LDicomNet::~LDicomNet
• LDicomNet::StartUp
• Class Members
• LDicomNet::Initialize

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

For an example, refer to LDicomNet::Initialize.