be.cardon.nativecall.cryptoapi
Class CryptoAPICalls

java.lang.Object
  extended by be.cardon.nativecall.cryptoapi.CryptoAPICalls

public class CryptoAPICalls
extends java.lang.Object

Native functions calls to CryptoAPI using the Java Native Interface (JNI).

The native functions are a set of the CryptoAPI functions. See the MSDN documentation to know exactely the meaning of the arguments and the error failure.

Note 1 : A lot of CryptoAPI function returns FALSE in case of error, and a call to GetLastError() in the same thread returns the Windows last error defined in WinError.h. The functions of this class don't return a boolean but throw a CryptoAPIException. Call the static method LastError.getLastError() to get the Windows last error number.

Note 2 : Some CryptoAPI function return a potentially large amount of data to an address provided as one of the parameters by the application (see MSDN article "Retrieving Data of Unknown Length"). This JNI implementation already called two times these functions : the first call retrieves the data length, a memory allocation is done and the second call retrieves the data.


Constructor Summary
CryptoAPICalls()
          Creates a new instance of CryptoAPICalls
 
Method Summary
 void CertCloseStore(int hCertStore, int dwFlags)
          Closes a certificate store handle.
 int CertDuplicateCertificateContext(int pCertContext)
          Duplicates a certificate context by incrementing its reference count.
 int CertEnumCertificatesInStore(int hCertStore, int pPrevCertContext)
          Retrieves the first or next certificate in a certificate store.
 void CertFreeCertificateChain(int pChainContext)
          Frees a certificate chain by reducing its reference count.
 void CertFreeCertificateContext(int pCertContext)
          Frees a certificate context by decrementing its reference count.
 int CertGetCertificateChain(int hChainEngine, int pCertContext, int pTime, int hAdditionalStore, int pChainPara, int dwFlags)
          Builds a certificate chain context starting from an end certificate and going back, if possible, to a trusted root certificate.
 byte[] CertGetCertificateContextProperty(int pCertContext, int dwPropId)
          retrieves the information contained in an extended property of a certificate context.
 java.lang.String CertGetNameStringW(int pCertContext, int dwType, int dwFlags, int TypePara)
          Obtains the subject or issuer name from a certificate CERT_CONTEXT structure and converts it to a null-terminated character string.
 java.lang.String CertNameToStrW(int dwCertEncodingType, int pName, int dwStrType)
          Converts an encoded name in a CERT_NAME_BLOB structure to a null-terminated character string.
 int CertOpenStore(int lpszStoreProvider, int dwMsgAndCertEncodingType, int hCryptProv, int dwFlags, int pvPara)
          Opens a certificate store using a specified store provider type.
 void CertVerifyRevocation(int dwEncodingType, int dwRevType, int cContext, int rgpvContext, int dwFlags, int pRevPara, int pRevStatus)
          Checks the revocation status of the certificates contained in the rgpvContext array.
 int[] CryptAcquireCertificatePrivateKey(int pCert, int dwFlags)
          Acquires a HCRYPTPROV cryptographic service provider (CSP) handle including access to its related key container and the dwKeySpec for a user's specified certificate context.
 int CryptAcquireContextW(java.lang.String containerName, java.lang.String providerName, int dwProvType, int dwFlags)
          Acquires a handle to the current user's key container within a particular CSP.
 int CryptCreateHash(int hProv, int Algid, int hKey)
          Creates an empty hash object.
 byte[] CryptDecrypt(int hKey, int hHash, boolean Final, int dwFlags, byte[] data)
          Decrypts a section of ciphertext by using the specified encryption key.
 void CryptDestroyHash(int hHash)
          Destroys an hash object.
 void CryptDestroyKey(int hKey)
          Destroys a key.
 byte[] CryptEncrypt(int hKey, int hHash, boolean Final, int dwFlags, byte[] data, int bufferSizeForOutput)
          Encrypts data.
 byte[] CryptGetHashParam(int hHash, int dwParam)
          Retuns the requested hash parameter.
 byte[] CryptGetKeyParam(int hKey, int dwParam)
          Retrieves data that governs the operations of a key.
 byte[] CryptGetProvParam(int hProv, int dwParam, int dwFlags)
          Retrieves parameters that govern the operations of a cryptographic service provider (CSP).
 int CryptGetUserKey(int hProv, int dwKeySpec)
          Gets a handle to the key exchange or signature key.
 void CryptHashData(int hHash, byte[] data, int dwFlags)
          Adds data to a specified hash object.
 void CryptReleaseContext(int hProv)
          Releases the handle acquired by the CryptAcquireContextW function.
 int CryptRetrieveObjectByUrlW(java.lang.String Url, java.lang.String ObjectOid, int dwRetrievalFlags, int dwTimeout, int pCredentials, int pvVerify, int pAuxInfo)
          retrieves the PKI object from a location specified by a URL.
 byte[] CryptSetHashParam(int hHash, int dwParam, byte[] Data)
          Sets a hash object parameter.
 void CryptSetProvParam(int hProv, int dwParam, int pbData, int dwFlags)
          Customizes the operations of a cryptographic service provider (CSP).
 byte[] CryptSignHash(int hHash, int dwKeySpec, int dwFlags)
          Signs the specified hash object.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

CryptoAPICalls

public CryptoAPICalls()
               throws CryptoAPIException
Creates a new instance of CryptoAPICalls

Throws:
CryptoAPIException
Method Detail

CryptAcquireContextW

public int CryptAcquireContextW(java.lang.String containerName,
                                java.lang.String providerName,
                                int dwProvType,
                                int dwFlags)
                         throws CryptoAPIException
Acquires a handle to the current user's key container within a particular CSP.

Wrapped function :

 BOOL WINAPI CryptAcquireContext(
 HCRYPTPROV* phProv,   [OUT] 
 LPCTSTR pszContainer, [IN]
 LPCTSTR pszProvider,  [IN]
 DWORD dwProvType,     [IN]
 DWORD dwFlags         [IN]
    );
Implemented as CryptAcquireContextW (unicode).

Parameters:
containerName - container name
providerName - provider name
dwProvType - Specifies the type of provider to acquire
dwFlags - Flag values. This parameter is usually set to zero, but some applications set one or more of the following flags.
Returns:
Handle of a CSP. When you have finished using the CSP, release the handle by calling the CryptReleaseContext function.
Throws:
CryptoAPIException

CryptReleaseContext

public void CryptReleaseContext(int hProv)
                         throws CryptoAPIException
Releases the handle acquired by the CryptAcquireContextW function.

Wrapped function:

 BOOL WINAPI CryptReleaseContext(
 HCRYPTPROV hProv  [IN]
 DWORD dwFlags     [IN] (Reserved for future use and must be zero)
 );
 

Parameters:
hProv - Handle of a cryptographic service provider (CSP) created by a call to CryptAcquireContextW.
Throws:
CryptoAPIException

CryptGetUserKey

public int CryptGetUserKey(int hProv,
                           int dwKeySpec)
                    throws CryptoAPIException
Gets a handle to the key exchange or signature key.

Wrapped function:

       
 BOOL CryptGetUserKey(
 HCRYPTPROV hProv,     [IN]
 DWORD dwKeySpec,      [IN]
 HCRYPTKEY* phUserKey  [OUT]
 );
 

Parameters:
hProv - HCRYPTPROV handle of a cryptographic service provider (CSP) created by a call to CryptAcquireContextW.
dwKeySpec - Identifies the private key to use from the key container. It can be AT_KEYEXCHANGE or AT_SIGNATURE . Additionally, some providers allow access to other user-specific keys through this function. For details, see the documentation on the specific provider.
Returns:
HCRYPTKEY handle of the retrieved keys. When you have finished using the key, delete the handle by calling the CryptDestroyKey function.
Throws:
CryptoAPIException

CryptDestroyKey

public void CryptDestroyKey(int hKey)
                     throws CryptoAPIException
Destroys a key.

Wrapped function:

   BOOL CryptDestroyKey(
   HCRYPTKEY hKey    in
 );
 

Parameters:
hKey - Handle of the key to be destroyed.
Throws:
CryptoAPIException

CryptGetKeyParam

public byte[] CryptGetKeyParam(int hKey,
                               int dwParam)
                        throws CryptoAPIException
Retrieves data that governs the operations of a key.

Wrapped function:

BOOL CryptGetKeyParam(
HCRYPTKEY hKey,
DWORD dwParam,
BYTE* pbData,
DWORD* pdwDataLen,
DWORD dwFlags,  (No flags are currently defined.)
);

Parameters:
hKey - Handle to the key being queried.
dwParam - Specifies the query being made. See MSDN documentation.
Returns:
The form of the returned data depends on the value of dwParam.
Throws:
CryptoAPIException

CryptDecrypt

public byte[] CryptDecrypt(int hKey,
                           int hHash,
                           boolean Final,
                           int dwFlags,
                           byte[] data)
                    throws CryptoAPIException
Decrypts a section of ciphertext by using the specified encryption key.

Wrapped function:

 BOOL WINAPI CryptDecrypt(
 HCRYPTKEY hKey,   IN  Handle to the key to use for the decryption. 
    An application obtains this handle by using either the CryptGenKey or CryptImportKey function. 
 HCRYPTHASH hHash, IN
 BOOL Final,       IN
 DWORD dwFlags,    IN
 BYTE* pbData,     IN/OUT 
 DWORD* pdwDataLen IN/OUT 
  );

Parameters:
hKey - Handle to the key to use for the decryption. An application obtains this handle by using either the CryptGenKey or CryptImportKey function. This key specifies the decryption algorithm to be used.
hHash - Handle to a hash object. If data is to be decrypted and hashed simultaneously, a handle to a hash object is passed in this parameter. The hash value is updated with the decrypted plaintext. This option is useful when simultaneously decrypting and verifying a signature. Before calling CryptDecrypt, the application must obtain a handle to the hash object by calling the CryptCreateHash function. After the decryption is complete, the hash value can be obtained through CryptGetHashParam, it can be signed using CryptSignHash, or it can be used to verify a digital signature using CryptVerifySignature. If no hash is to be done, this parameter must be zero.
Final - Specifies whether this is the last section in a series being decrypted. This value is TRUE if this is the last or only block. If this is not the last block, this value is FALSE.
dwFlags - Defined flags : CRYPT_OAEP.
data - Data to be decrypted
Returns:
Byte array with the decrypted data (plain text).
Throws:
CryptoAPIException

CryptEncrypt

public byte[] CryptEncrypt(int hKey,
                           int hHash,
                           boolean Final,
                           int dwFlags,
                           byte[] data,
                           int bufferSizeForOutput)
                    throws CryptoAPIException
Encrypts data.

Wrapped function:

BOOL WINAPI CryptEncrypt(
  HCRYPTKEY hKey,   [in] Handle to the encryption key
  HCRYPTHASH hHash, [in] If data is to be hashed and encrypted simultaneously, a handle to a hash object can be passed in the hHash parameter. 
  BOOL Final,      [in] Boolean value that specifies whether this is the last section in a series being encrypted.
  DWORD dwFlags,  [in] The following dwFlags =CRYPT_OAEP
  BYTE* pbData,   [in, out] Pointer to a buffer that contains the data to be encrypted => IN ONLY
  DWORD* pdwDataLen,  [in, out] Pointer to a DWORD value that contains the length of the data buffer = IN ONLY
  DWORD dwBufLen  [in] DWORD value that specifies the length, in bytes, of the input pbData buffer => must be large enough, depending on the algorithm used.
 );

Throws:
CryptoAPIException

CryptCreateHash

public int CryptCreateHash(int hProv,
                           int Algid,
                           int hKey)
                    throws CryptoAPIException
Creates an empty hash object.

Wrapped function:

 BOOL WINAPI CryptCreateHash(
 HCRYPTPROV hProv,  [in] Handle of a cryptographic service provider (CSP) created by a call to CryptAcquireContext. 
 ALG_ID Algid, [in] ALG_ID that identifies the hash algorithm to use.
 HCRYPTKEY hKey,  [in] If the type of hash algorithm is a keyed hash, such as the HMAC or Message Authentication Code (MAC) algorithm
    For nonkeyed algorithms, this parameter must be set to zero.
 DWORD dwFlags, [in] Reserved for future use and must be zero. ==> DELETED !
 HCRYPTHASH* phHash [out] Address to which the function copies a handle to the new hash object. => returns the handle
 );
When you have finished using the hash object, release the handle by calling the CryptDestroyHash function.

Throws:
CryptoAPIException

CryptDestroyHash

public void CryptDestroyHash(int hHash)
                      throws CryptoAPIException
Destroys an hash object. BOOL WINAPI CryptDestroyHash( HCRYPTHASH hHash );

Throws:
CryptoAPIException

CryptHashData

public void CryptHashData(int hHash,
                          byte[] data,
                          int dwFlags)
                   throws CryptoAPIException
Adds data to a specified hash object.

Wrapped function:

 BOOL WINAPI CryptHashData(
 HCRYPTHASH hHash, IN
 BYTE* pbData,     IN
 DWORD dwDataLen,  IN
 DWORD dwFlags     IN
 );

Throws:
CryptoAPIException

CryptSignHash

public byte[] CryptSignHash(int hHash,
                            int dwKeySpec,
                            int dwFlags)
                     throws CryptoAPIException
Signs the specified hash object.

The signature returned is in little endian ! You must reverse the bytes to big endian

Wrapped function:

BOOL WINAPI CryptSignHash(
HCRYPTHASH hHash, [in] Handle of the hash object to be signed
DWORD dwKeySpec, [in] Identifies the private key to use from the provider's container :AT_KEYEXCHANGE or AT_SIGNATURE
LPCTSTR sDescription, [in]This parameter is no longer used and must be set to NULL to prevent security vulnerabilities. =>DELETED!
DWORD dwFlags, : CRYPT_NOHASHOID, CRYPT_X931_FORMAT
BYTE* pbSignature, [out] Pointer to a buffer receiving the signature data => RETURN VALUE
DWORD* pdwSigLen [in, out] Pointer to a DWORD value that specifies the size, in bytes, of the pbSignature buffer.
);
 When the function returns, the DWORD value contains the number of bytes stored in the buffer.  => IN ONLY

Throws:
CryptoAPIException

CryptSetHashParam

public byte[] CryptSetHashParam(int hHash,
                                int dwParam,
                                byte[] Data)
                         throws CryptoAPIException
Sets a hash object parameter.

Wrapped function:

BOOL WINAPI CryptSetHashParam(
HCRYPTHASH hHash, [in] A handle to the hash object on which to set parameters. 
DWORD dwParam, [in]
BYTE* pbData, [in] A value data buffer
DWORD dwFlags [in] This parameter is reserved for future use and must be set to zero.  => DELETED
);

Throws:
CryptoAPIException

CryptGetHashParam

public byte[] CryptGetHashParam(int hHash,
                                int dwParam)
                         throws CryptoAPIException
Retuns the requested hash parameter.

Wrapped function:

BOOL WINAPI CryptGetHashParam(
HCRYPTHASH hHash, [in] Handle of the hash object to be queried. 
DWORD dwParam, [in] Query type. This parameter can be set to one of the following queries. 
BYTE* pbData, [out] Pointer to a buffer that receives the specified value data. => RETURN VALUE
DWORD* pdwDataLen, [in, out] Pointer to a DWORD value specifying the size, in bytes, of the pbData buffer.
DWORD dwFlags [in] Reserved for future use and must be zero. => DELETED
);

Throws:
CryptoAPIException

CertCloseStore

public void CertCloseStore(int hCertStore,
                           int dwFlags)
                    throws CryptoAPIException
Closes a certificate store handle.

Wrapped function:

BOOL WINAPI CertCloseStore(
HCERTSTORE hCertStore, [in] Handle of the certificate store to be closed. 
 DWORD dwFlags [in] Typically, this parameter uses the default value zero. 
 The default is to close the store with memory remaining allocated for contexts 
 that have not been freed. In this case, no check is made to determine whether memory 
 for contexts remains allocated. 
);

Throws:
CryptoAPIException

CertEnumCertificatesInStore

public int CertEnumCertificatesInStore(int hCertStore,
                                       int pPrevCertContext)
                                throws CryptoAPIException
Retrieves the first or next certificate in a certificate store.

Wrapped function:

PCCERT_CONTEXT WINAPI CertEnumCertificatesInStore(
HCERTSTORE hCertStore, [in] Handle of a certificate store
PCCERT_CONTEXT pPrevCertContext [in] Pointer to the CERT_CONTEXT of the previous certificate context found.
);

Throws:
CryptoAPIException

CertDuplicateCertificateContext

public int CertDuplicateCertificateContext(int pCertContext)
                                    throws CryptoAPIException
Duplicates a certificate context by incrementing its reference count.

Wrapped function:

PCCERT_CONTEXT WINAPI CertDuplicateCertificateContext(
PCCERT_CONTEXT pCertContext
);

Throws:
CryptoAPIException

CertOpenStore

public int CertOpenStore(int lpszStoreProvider,
                         int dwMsgAndCertEncodingType,
                         int hCryptProv,
                         int dwFlags,
                         int pvPara)
                  throws CryptoAPIException
Opens a certificate store using a specified store provider type.

Wrapped function:

 
HCERTSTORE WINAPI CertOpenStore(
LPCSTR lpszStoreProvider, [in] Specifies the store provider type : CERT_STORE_PROV_SYSTEM...
DWORD dwMsgAndCertEncodingType, [in]
HCRYPTPROV hCryptProv, [in]
DWORD dwFlags, [in]
const void* pvPara [in]
);

Throws:
CryptoAPIException

CertFreeCertificateContext

public void CertFreeCertificateContext(int pCertContext)
                                throws CryptoAPIException
Frees a certificate context by decrementing its reference count.

Wrapped function:

BOOL WINAPI CertFreeCertificateContext(
PCCERT_CONTEXT pCertContext [in] Pointer to the CERT_CONTEXT to be freed. 
);

Throws:
CryptoAPIException

CertGetNameStringW

public java.lang.String CertGetNameStringW(int pCertContext,
                                           int dwType,
                                           int dwFlags,
                                           int TypePara)
                                    throws CryptoAPIException
Obtains the subject or issuer name from a certificate CERT_CONTEXT structure and converts it to a null-terminated character string. Implemented as CertGetNameStringW (Unicode) and CertGetNameStringA (ANSI).

Wrapped function:

DWORD WINAPI CertGetNameString(
PCCERT_CONTEXT pCertContext, in
DWORD dwType, in
DWORD dwFlags, in
void* pvTypePara, in
LPTSTR pszNameString, [out] Pointer to an allocated buffer to receive the returned string
DWORD cchNameString [in] Size, in characters, allocated for the returned string
);

Throws:
CryptoAPIException

CertVerifyRevocation

public void CertVerifyRevocation(int dwEncodingType,
                                 int dwRevType,
                                 int cContext,
                                 int rgpvContext,
                                 int dwFlags,
                                 int pRevPara,
                                 int pRevStatus)
                          throws CryptoAPIException
Checks the revocation status of the certificates contained in the rgpvContext array.

Wrapped function:

BOOL WINAPI CertVerifyRevocation(
DWORD dwEncodingType,
DWORD dwRevType,
DWORD cContext,
PVOID rgpvContext[],
DWORD dwFlags,
PCERT_REVOCATION_PARA pRevPara, [in optional]
PCERT_REVOCATION_STATUS pRevStatus [in out]
);

Throws:
CryptoAPIException

CryptAcquireCertificatePrivateKey

public int[] CryptAcquireCertificatePrivateKey(int pCert,
                                               int dwFlags)
                                        throws CryptoAPIException
Acquires a HCRYPTPROV cryptographic service provider (CSP) handle including access to its related key container and the dwKeySpec for a user's specified certificate context.

Wrapped function:

BOOL WINAPI CryptAcquireCertificatePrivateKey(
PCCERT_CONTEXT pCert,
DWORD dwFlags,
void* pvReserved, (Reserved for future use and must be NULL.)
HCRYPTPROV* phCryptProv,
DWORD* pdwKeySpec,
   to use from the acquired provider's key container. It can be 
   AT_KEYEXCHANGE or AT_SIGNATURE. 
BOOL* pfCallerFreeProv [out] Pointer to a BOOL flag. => INDEX 2
);

Parameters:
pCert - Handle to a CERT_CONTEXT.
dwFlags - Flags.
Returns:
an array of two integers :
  • [0] the first integer phCryptProv is a pointer to the HCRYPTPROV handle.
  • [1] the second integer pdwKeySpec is a pointer to a DWORD value identifying the private key.
  • Throws:
    CryptoAPIException

    CryptGetProvParam

    public byte[] CryptGetProvParam(int hProv,
                                    int dwParam,
                                    int dwFlags)
                             throws CryptoAPIException
    Retrieves parameters that govern the operations of a cryptographic service provider (CSP).

    Wrapped function:

    BOOL WINAPI CryptGetProvParam(
    HCRYPTPROV hProv,
    DWORD dwParam,
    BYTE* pbData, [out] Pointer to a buffer to receive the data
    DWORD* pdwDataLen, [in, out] Pointer to a DWORD value specifying the size, in 
     bytes, of the buffer pointed to by the pbData parameter. When the function 
     returns, the DWORD value contains the number of bytes stored or to be stored in the buffer. 
    DWORD dwFlags
    );
    

    Throws:
    CryptoAPIException

    CryptSetProvParam

    public void CryptSetProvParam(int hProv,
                                  int dwParam,
                                  int pbData,
                                  int dwFlags)
                           throws CryptoAPIException
    Customizes the operations of a cryptographic service provider (CSP).

    Wrapped function:

    BOOL WINAPI CryptSetProvParam(
      HCRYPTPROV hProv,   IN
      DWORD dwParam,      IN
      const BYTE* pbData, IN
      DWORD dwFlags       IN
      );
    

    Parameters:
    hProv - The handle of a CSP for which to set values.
    dwParam - Specifies the parameter to set (see MSDN)
    pbData - A pointer to a data buffer that contains the value to be set as a provider parameter.
    dwFlags - optional flags.
    Throws:
    CryptoAPIException - if the native function returns false (see MSDN).

    CertGetCertificateContextProperty

    public byte[] CertGetCertificateContextProperty(int pCertContext,
                                                    int dwPropId)
                                             throws CryptoAPIException
    retrieves the information contained in an extended property of a certificate context.

    Wrapped function:

    BOOL WINAPI CertGetCertificateContextProperty(
    PCCERT_CONTEXT pCertContext,
    DWORD dwPropId,
    void* pvData,  [out] A pointer to a buffer to receive the data as determined by dwPropId
    DWORD* pcbData [in, out] A pointer to a DWORD value that specifies the size, 
     in bytes, of the buffer pointed to by the pvData parameter. When the
     function returns, the DWORD value contains the number of bytes to be 
     stored in the buffer.
    );
    

    Throws:
    CryptoAPIException

    CryptRetrieveObjectByUrlW

    public int CryptRetrieveObjectByUrlW(java.lang.String Url,
                                         java.lang.String ObjectOid,
                                         int dwRetrievalFlags,
                                         int dwTimeout,
                                         int pCredentials,
                                         int pvVerify,
                                         int pAuxInfo)
                                  throws CryptoAPIException
    retrieves the PKI object from a location specified by a URL.

    Wrapped function:

    BOOL WINAPI CryptRetrieveObjectByUrl(
    LPCTSTR pszUrl,
    LPCSTR pszObjectOid,
    DWORD dwRetrievalFlags,
    DWORD dwTimeout,
    LPVOID* ppvObject, [out] Pointer to a pointer to the returned object. 
    HCRYPTASYNC hAsyncRetrieve, => NULL (deleted)
    PCRYPT_CREDENTIALS pCredentials, [in, optional] 
    LPVOID pvVerify, [in, optional]
    PCRYPT_RETRIEVE_AUX_INFO pAuxInfo
    );
    

    Throws:
    CryptoAPIException

    CertNameToStrW

    public java.lang.String CertNameToStrW(int dwCertEncodingType,
                                           int pName,
                                           int dwStrType)
                                    throws CryptoAPIException
    Converts an encoded name in a CERT_NAME_BLOB structure to a null-terminated character string.

    Wrapped function:

    DWORD WINAPI CertNameToStr(
    DWORD dwCertEncodingType,
    PCERT_NAME_BLOB pName,
    DWORD dwStrType,
    LPTSTR psz,
    DWORD csz
    );
    

    Throws:
    CryptoAPIException

    CertGetCertificateChain

    public int CertGetCertificateChain(int hChainEngine,
                                       int pCertContext,
                                       int pTime,
                                       int hAdditionalStore,
                                       int pChainPara,
                                       int dwFlags)
                                throws CryptoAPIException
    Builds a certificate chain context starting from an end certificate and going back, if possible, to a trusted root certificate.

    Wrapped function:

    BOOL WINAPI CertGetCertificateChain(
    HCERTCHAINENGINE hChainEngine,
    PCCERT_CONTEXT pCertContext,
    LPFILETIME pTime,
    HCERTSTORE hAdditionalStore,
    PCERT_CHAIN_PARA pChainPara,
    DWORD dwFlags,
    LPVOID pvReserved, (Reserved parameter and must be NULL.)
    PCCERT_CHAIN_CONTEXT* ppChainContext
    );
    

    Parameters:
    hChainEngine - Handle of the chain engine (name space and cache) to be used. If hChainEngine is NULL, the default chain engine, HCCE_CURRENT_USER, is used. Can be set to HCCE_LOCAL_MACHINE.
    pCertContext - Pointer to the CERT_CONTEXT of the end certificate, the certificate for which a chain is being built. This certificate context will be the zero-index element in the first simple chain.
    pTime - Pointer to a FILETIME variable that indicates the time for which the chain is to be validated. Note that the time does not affect trust list, revocation, or root store checking. The current system time is used if NULL is passed to this parameter.
    hAdditionalStore - Handle of any additional store to search for supporting certificates and certificate trust lists (CTLs). This parameter can be NULL if no additional store is to be searched.
    pChainPara - Pointer to a CERT_CHAIN_PARA structure that includes chain-building parameters.
    dwFlags - Flag values that indicates special processing. See MSDN.
    Returns:
    handle to the chain context created. When you have finished using the chain context, release the chain by calling the CertFreeCertificateChain function.
    Throws:
    CryptoAPIException

    CertFreeCertificateChain

    public void CertFreeCertificateChain(int pChainContext)
                                  throws CryptoAPIException
    Frees a certificate chain by reducing its reference count. If the reference count becomes zero, memory allocated for the chain is released.

    Wrapped function:

    VOID WINAPI CertFreeCertificateChain(
    PCCERT_CHAIN_CONTEXT pChainContext
    );
    

    Parameters:
    pChainContext - Pointer to a CERT_CHAIN_CONTEXT certificate chain context to be freed. If the reference count on the context reaches zero, the storage allocated for the context is freed.
    Throws:
    CryptoAPIException