CryptXML Functions

The cryptographic XML functions provide an API for creating and representing digital signatures by using XML formatted data. For information about XML formatted signatures, see the XML-Signature Syntax and Processing specification at https://go.microsoft.com/fwlink/p/?linkid=139649.

Opens an XML digital signature to encode and returns a handle of the opened Signature element. The handle encapsulates a document context with a single CRYPT_XML_SIGNATURE structure and remains open until the CryptXmlClose function is called.

Opens an XML digital signature to decode and returns the handle of the document context that encapsulates a CRYPT_XML_SIGNATURE structure. The document context can include one or more Signature elements.

Time stamps the specified subject and optionally returns a pointer to a SIGNER_CONTEXT structure that contains a pointer to a BLOB. This function supports Authenticode time stamping. To perform X.509 Public Key Infrastructure (RFC 3161) time stamping, use the SignerTimeStampEx2 function.

Time stamps the specified subject and optionally returns a pointer to a SIGNER_CONTEXT structure that contains a pointer to a BLOB. This function can be used to perform X.509 Public Key Infrastructure, RFC 3161–compliant, time stamps.

Time stamps the specified subject and supports setting time stamps on multiple signatures.

Base Cryptography Functions

Base cryptographic functions provide the most flexible means of developing cryptography applications. All communication with a cryptographic service provider (CSP) occurs through these functions.

A CSP is an independent module that performs all cryptographic operations. At least one CSP is required with each application that uses cryptographic functions. A single application can occasionally use more than one CSP.

If more than one CSP is used, the one to use can be specified in the CryptoAPI cryptographic function calls. One CSP, the Microsoft Base Cryptographic Provider, is bundled with the CryptoAPI. This CSP is used as a default provider by many of the CryptoAPI functions if no other CSP is specified.

Each CSP provides a different implementation of the cryptographic support provided to CryptoAPI. Some provide stronger cryptographic algorithms; others contain hardware components, such as smart cards. In addition, some CSPs can occasionally communicate directly with users, such as when digital signatures are performed by using the user's signature private key.

Certificate Store Functions

A user site can, over time, collect many certificates. Typically, a site has certificates for the user of the site as well as other certificates that describe those individuals and entities with whom the user communicates. For each entity, there can be more than one certificate. For each individual certificate, there should be a chain of verifying certificates that provides a trail back to a trusted root certificate. Certificate stores and their related functions provide functionality to store, retrieve, enumerate, verify, and use the information stored in the certificates.

Allows an application to be notified when there is a difference between the contents of a cached store and the contents of the store that is persisted to storage. It also provides desynchronization of the cached store, if necessary, and provides a means to commit changes made in the cached store to persisted storage.

Certificate Functions

Most Certificate functions have related functions to deal with CRLs and CTLs. For more information about related CRL and CTL functions, see Certificate Revocation List Functions and Certificate Trust List Functions.

Message Functions

Low-level message functions create and work directly with PKCS #7 messages. These functions encode PKCS #7 data for transmission and decode PKCS #7 data received. They also decrypt and verify the signatures of received messages. For an overview of the PKCS #7 standard and low-level messages, see Low-level Messages.

Simplified message functions are at a higher level and wrap several low-level message functions and certificate functions into single functions that perform a specific task in a specific manner. These functions reduce the number of function calls needed to accomplish a task, thereby simplifying CryptoAPI use. For an overview of simplified messages, see Simplified Messages.

Low-level Message Functions

Simplified Message Functions

Low-level Message Functions

Low-level message functions provide the functionality necessary to encode data for transmission and to decode PKCS #7 messages received. Functionality is also provided to decrypt and verify the signatures of received messages. Use of these low-level message functions in most applications is not recommended. For most applications, the use of Simplified Message Functions, which wrap several low-level message functions into a single function call, is preferred.

Exports the public key information associated with the provider's corresponding private key. This function differs from CryptExportPublicKeyInfo in that the user can specify the public key algorithm, thereby overriding the default provided by the CSP.

Converts and imports the public key information into the provider, and returns a handle of the public key. Additional parameters (over those specified by CryptImportPublicKeyInfo) that can be used to override defaults are provided to supplement CERT_PUBLIC_KEY_INFO.

Returns a SIP_INDIRECT_DATA structure that contains a hash of the supplied SIP_SUBJECTINFO structure, the digest algorithm, and an encoding attribute. The hash can be used as an indirect reference to the data.

Enhanced Key Usage Functions

The following functions deal with the enhanced key usage (EKU) extension and the EKU extended property of certificates. The EKU extension and extended property specify and limit the valid uses of a certificate. The extensions are part of the certificate itself. They are set by the issuer of the certificate and are read-only. Certificate-extended properties are values associated with a certificate that can be set in an application.

Key Identifier Functions

Key identifier functions allow the user to create, set, retrieve, or locate a key identifier or its properties.

A key identifier is the unique identifier of a public/private key pair. It can be any unique identifier but is usually the 20-byte SHA1 hash of an encoded CERT_PUBLIC_KEY_INFO structure. A key identifier can be obtained through the certificate's CERT_KEY_IDENTIFIER_PROP_ID. The key identifier allows the use of that key pair to encrypt or decrypt messages without using the certificate.

Attempts to decode the outer layer of a BLOB as a PFX packet and to decrypt it with the given password.

Certificate Services Backup and Restore Functions

Certificate Services includes functions for backing up and restoring the Certificate Services database. These Certificate Services backup and restore functions are contained in Certadm.dll. Unlike the other API elements associated with Certificate Services, these functions are not encapsulated in an object that can be used to call class methods. Instead, the backup and restore APIs are called by first loading the Certadm.dll library into memory by calling LoadLibrary and then determining the address of the functions by calling GetProcAddress. When you have finished calling the Certificate Services backup and restore functions, call FreeLibrary to free Certadm.dll resources from memory.

If CoInitializeEx was previously called in the same thread used to call the Certificate Services backup and restore APIs, the COINIT_APARTMENTTHREADED flag must have been passed to CoInitializeEx. That is, when using the same thread, you cannot call the Certificate Services backup and restore API if the thread has previously passed in the COINIT_MULTITHREADED flag in a call to CoInitializeEx.

The Certificate Services Backup APIs are defined in Certbcli.h. However, when you create your program, use Certsrv.h as the include file.

Callback Functions

The callback functions in this section are used to register or install application-defined certificate store providers and to provide related functionality through callback functions. Callback functions are implemented by an application and are called by CryptoAPI functions. Callback functions enable the application to control, in part, the way that CryptoAPI functions manipulate data.