Introducing Certificate Server

Microsoft® Certificate Server provides customizable services for issuing and managing certificates used in software security systems employing public-key cryptography. Certificate Server performs a central role in the management of software security systems to enable secure communications across the Internet, corporate intranets, and other nonsecure networks.

Certificate Server receives requests for new certificates over transports such as RPC, HTTP, or e-mail. It checks each request against custom or site-specific policies, sets optional properties for the certificate to be issued, and issues the certificate. Certificate Server allows administrators to add elements to a certificate revocation list (CRL), and publish a signed CRL on a regular basis. Programmable interfaces are included for developers to create support for additional transports, policies, and certificate properties and formats.

Certificate Server generates certificates in standard X.509 format. Certificates in X.509 format are commonly used to authenticate servers and clients performing secure communications using the Secure Sockets Layer (SSL) protocol.


Certificate Server Usage Scenarios

Microsoft® Certificate Server is designed for web-based applications that require authentication and secure communications based on the Secure Sockets Layer (SSL) protocol. It can also support other certificate-based applications such as secure e-mail like Secure/Multipurpose Internet Mail Extensions (S/MIME), secure payment such as Secure Electronic Extensions (SET), and digital signatures like Microsoft Authenticode™. In the case of SSL, an organization can use the certificate server to issue both server and client certificates in a standard X.509 version 3.0 format. The organization may elect to issue all certificates from a single certificate server or use multiple certificate servers that are chained together in a Certificate Authority (CA) hierarchy.

At the most basic level, the role of Certificate Server is to receive a PKCS #10 certificate request, verify the information in the request and issue a corresponding X.509 certificate (or, possibly, certificate chain) in a PKCS #7 format. In the case of a user who wants to obtain a certificate for a web browser, a certificate request is typically generated by visiting a web site and enrolling for a certificate. To enroll, the user enters identifying information (for example, name, address, e-mail) into an HTML form, a key pair is generated and the public key is sent in a PKCS #10 to the CA. If all identifying information meets the CA criteria for granting a request, the Certificate Server generates the certificate which is downloaded to the user's browser.


Inter-networking in Large Organizations

The following examples show situations where Microsoft® Certificate Server typically grants certificates to users within an organization so they can conduct secure communications across the Internet and gain access to the corporate intranet.

  • Branch offices where the Internet supplements or serves as a corporate WAN.
  • Supplier or vendor relationship where intranet access is granted to groups of users from key partners.

The Certificate Authority (CA) issuing the certificates can implement policies tailored to each specific case. An example of such a policy would include the following:

  • Use authenticated RPC to receive certificate requests and transmit completed certificates.
  • Check that the Issuer Organization and Issuer Organizational Unit information specified in certificate requests correctly identifies the CA server organization (specified in the CA server configuration file).
  • Check that the Subject Common Name information specified in certificate requests matches the authenticated user name.


Inter-networking with Partner Organizations

Microsoft® Certificate Server can be used to grant certificates to end-users within an organization so they can conduct secure communications across the Internet and gain access to the corporate intranet. Two examples:

  1. Branch offices. The Internet supplements or serves as a corporate WAN.
  2. Supplier/vendor relationships. Intranet access is granted to groups of users from key partners.

The Certificate Authority (CA) issuing the certificates can implement policies tailored to each specific case. An example of such a policy would include the following:

  • Use authenticated RPC to receive certificate requests and transmit completed certificates.
  • Check that the Issuer Organization and Issuer Organizational Unit information specified in certificate requests correctly identifies the CA server's organization (specified in the CA server's configuration file).
  • Check that the Subject Common Name information specified in certificate requests matches the authenticated user name.


Customer Registration

Microsoft® Certificate Server registers users for services on the Internet by following these conditions:

  • Receives certificate requests and issues completed certificates over HTTP.
  • Checks information in a certificate request against an external database.
  • Optionally defers completion of the request process so the customer can be personally contacted for verification.

This set of conditions comprise a typical offline approval policy that would be appropriate when there is need for a high degree of user validation.


Interoperability

By using industry-standard certificate formats and open interfaces, Microsoft® Certificate Server is interoperable with many products and technologies that support the use of digital certificates. The following are examples of products and technologies that support digital certificates.


Web Servers

On a corporate intranet or on the Internet, servers such as Microsoft® Internet Information Server (IIS) can perform client authentication for secure communications using certificates generated by Microsoft Certificate Server. Certificate Server can also generate server certificates used by IIS and other Web servers to provide server authentication to assure clients that they are communicating with the intended entity.


Web Browsers

Microsoft® Certificate Server can be used to issue certificates to browsers which support client authentication, such as Microsoft Internet Explorer version 3.0 or later, or Netscape Navigator 3.0. Internet Explorer can install server certificates for Microsoft Internet Information Server (IIS) and other Web servers used for server authentication such as Netscape Enterprise Server. Internet Explorer also uses certificates for client authentication on servers that the user wants to access. You can view and examine the details of certificates that are installed in Internet Explorer.

Complete these steps to view certificates installed in Internet Explorer:
  1. Start Internet Explorer.
  2. If running Internet Explorer 3.x, on the View menu, click Options; then click the Security tab. If running Internet Explorer 4.x, on the View menu, click Internet Options; then click the Content tab.
  3. If running Internet Explorer 3.x, click Personal to view client certificates or Sites to view server certificates. If running Internet Explorer 4.x, click Personal to view client certificates or Authorities to view server certificates.
  4. If there are any certificate names shown in the list box, click on a name; then click the View Certificate button.
  5. Click on each item in the Fields list box to view the details of the certificate's fields in the Details text box.


LDAP Directories

Microsoft® Certificate Server's programmability makes it possible to issue certificates to any directory compliant with Lightweight Directory Access Protocol (LDAP). LDAP is an easily implemented subset of the X.500 DAP standard for directory services. LDAP has strong industry support and is expected to become an industry standard for directory services. Certificate Server compliance with LDAP implies it can interoperate with policy tools and other third-party applications that support LDAP directory services.


Microsoft Internet Security Framework

Microsoft® Certificate Server is part of the Microsoft Internet Security Framework (ISF), which is an integral part of the Microsoft Windows® security model. The integration of ISF on the Microsoft Windows NT® platform allows certificates to be mapped to Windows NT users and groups. Network administrators can then use standard Windows NT administrative tools, such as access control lists, to handle Internet and intranet security matters. Windows NT users benefit from the convenience of a single logon to access organization resources on the corporate network, corporate intranet, or the Internet.


Microsoft Exchange Server

Microsoft® Exchange Server 4.0 and 5.0 include Key Management Server (KMS), a combination certificate-issuing server and key-recovery server. KMS allows Microsoft Exchange users to send digitally-signed and encrypted mail to other Microsoft Exchange users. In a future release of Microsoft Exchange Server, all certificate-issuing functions of KMS will be replaced by Microsoft Certificate Server. This will allow Microsoft Exchange to take advantage of the flexible, standards-based capabilities of Microsoft Certificate Server. The KMS will continue to provide private-key recovery services. This will enable users and administrators to recover encrypted e-mail data in the event the user's private keys are lost or the user leaves the company.


Certificate Server Features

Microsoft® Certificate Server allows an organization to manage the issuing, renewal and revocation of certificates. It has a number of features which make it valuable to organizations that do not choose to rely upon external certificate authorities and who need a flexible tool that can be adapted to the needs of the organization.


Policy Independence

Certificates are granted according to policies that define criteria that requesters must meet in order to receive a certificate. For example, one policy may be to grant commercial certificates only if applicants present their identification in person. Another policy may grant credentials based on e-mail requests. An agency that issues credit cards may choose to consult a database and make phone inquiries before issuing a card.

Policies are implemented in policy modules written in Java, Microsoft® Visual Basic®, or Microsoft C/C++. Microsoft Certificate Server functions are isolated from any changes in policy that an agency might implement. Changes in policy can be fully implemented in the server policy module code.


Transport Independence

Certificates can be requested and distributed through any transport mechanism. Microsoft® Certificate Server accepts certificate requests from an applicant through HTTP, RPC, disk file, or by custom transport. Certificate Server posts certificates to the applicant through HTTP, RPC, disk file, or custom transport.

Transports are supported by intermediary applications and exit module DLLs, usually written in Microsoft C/C++. The intermediary applications and exit modules isolate the Certificate Server functions from communicating with any specific transport.


Adherence to Standards

Microsoft® Certificate Server accepts standard PKCS #10 requests and issues X.509 version 1.0 and 3.0 certificates. Other certificate formats can be supported by modules called extension handlers. Certificate Server works with non-Microsoft clients and browsers, and non-Microsoft Web servers. Certificate Server can write certificates to any database or directory service supported by a custom exit module.


Key Management

The security of a certification system depends on how the private keys are protected. The design of Microsoft® Certificate Server ensures that it cannot be misused by an individual to perform unauthorized access of private key information. Because key management in Certificate Server is performed by Microsoft CryptoAPI, Certificate Server is isolated from these confidential pieces of data. Also, the CryptoAPI functions can employ the services of anything from software modules to hardware-based key engines for the generation and protection of keys. This allows organizations using Certificate Server to select the appropriate key-management system strength for the organization.


High Reliability

Microsoft® Certificate Server leverages the reliability features incorporated into Microsoft Windows NT® Server network operating system. The Windows NT architecture protects applications from damaging each other and the operating system by employing structured exception handling and a recoverable file system called New Technology Filing System (NTFS). Windows NT provides protection through its built-in security and has United States Government C2 certification.


Scalability

Microsoft® Certificate Server is a cornerstone for implementing public-key cryptography-based security on corporate intranets and other forms of enterprise-wide networks, as well as on the Internet. Using Certificate Server, it is easier to support large numbers of users since there is no need to distribute password databases. Certificate Server can be deployed on multiple servers in large organizations that need the flexibility of more than one Certificate Authority.


Certificate Server Architecture

Microsoft® Certificate Server consists of the Server Engine that handles certificate requests, and other modules that communicate with the Server Engine to perform tasks.

The preceding diagram illustrates the flow of information between the Certificate Server and other components. These components include the Server Engine, server database, an external Intermediary application, one or more exit modules, a policy module, administration tools, utility programs, and optional extension handlers.


Server Engine

The Server Engine is the core component of Microsoft® Certificate Server. The engine acts as a broker for all requests it receives, driving the flow of information between components during the processing of a request and generation of a certificate. At each processing stage, the engine interacts with the various modules to ensure appropriate action is taken based on the state of the request.


Intermediary

The Intermediary is the architectural component that receives new certificate requests from clients and submits them to the Server Engine. The intermediary is composed of two parts, the intermediary application that performs actions on behalf of clients, and the Certificate Server client interface (CertCli.dll) that handles communications between the intermediary application and the server engine.

Intermediaries can be written to handle certificate requests from different types of clients and across multiple transports. Microsoft® Internet Information Server is an intermediary that provides support for clients over HTTP. Intermediaries can also check on the status of a previously submitted request and obtain the Certificate Server's configuration information.


Server Database

Certificate Server includes a Server Database that maintains status information and a log of all issued certificates and certificate revocation lists (CRLs). The database is composed of two parts, the Server Log and the Server Queue.

The Server Log stores all certificates and CRLs issued by the server so administrators can track, audit and archive server activity. In addition, the Server Log is used by the Server Engine to store pending revocations prior to publishing them in the CRL. The Server Log also stores recent certificate requests for a configurable period of time in case a problem is encountered when issuing a certificate (for example, a delivery failure). The Certificate Log Utility provides administrative access to this part of the Certificate Server database.

The Server Queue maintains status information (receipt, parsing, authorization, signing, dispatch) as a certificate request is being processed by the server. The Certificate Queue Utility provides administrative access to this part of the Certificate Server database.


Admin Tools

Administration Tools

Microsoft® Certificate Server includes Web-based administration tools that provide services for accessing the data contained in the Server Database. Additional administration tools may be written using the administration interface.


Policy Module

The Policy Module contains the set of rules governing issuance of certificates. All requests received by the Server Engine are passed to the Policy Module for validation. Policy modules are also used to parse any supplemental information provided within a request and set properties on the certificate accordingly.

The Policy Module is fully replaceable and customizable through an Automation interface to the Server Engine.


Extension Handlers

Extension handlers work in tandem with the Policy Module to set custom extensions on a certificate. Each extension handler acts as a template for the custom extensions that should appear in a certificate. The appropriate extension handler must be loaded by the Policy Module when needed. Extension handlers can also be loaded by an exit module and used to decode custom extensions in a certificate.


Exit Modules

Exit Modules publish completed certificates through any number of transports or protocols. By default, the server notifies each exit module installed on the server whenever a certificate is published.

A Component Object Model (COM) interface for writing custom exit modules for different transports/protocols or custom delivery options is provided with Microsoft® Certificate Server. For example, an LDAP exit module might be used to publish only client certificates in a Directory Service and not server certificates. In this case, the exit module can use the COM interface to determine the type of certificate that the server is issuing and filter out any that are not client certificates.


Certificate Repository

Certificates can be stored in any external database or directory service supported by a custom exit module.


Processing Certificate Requests

Microsoft® Certificate Server performs the following steps when processing a certificate request:

  1. Request reception. The certificate request is sent by the client to an intermediary application, which formats it into a PKCS #10 format request and submits it to the Server Engine.
  2. Request approval. The Server Engine calls the Policy Module, which queries request properties, decides whether the request is authorized or not, and sets optional certificate properties.
  3. Certificate formation. If the request is approved, the Server Engine takes the request, and any properties requested by the Policy Module, and builds a complete certificate.
  4. Certificate publication. The Server Engine stores the completed certificate in the certificate store and notifies the intermediary application of the request status. If the exit module has so requested, the Server Engine will notify it of a certificate issuance event. This allows the exit module to perform further operations such as publishing the certificate to a directory service. Meanwhile, the intermediary gets the published certificate from the certificate store and passes it back to the client.

The following diagram illustrates how a certificate request is processed by Microsoft Certificate Server:


Certificate Enrollment

As illustrated in the following diagram, HTTP-based enrollment is handled by Microsoft® Internet Information Server (IIS). The enrollment code on the IIS server can be configured to talk to multiple Certificate Servers by supplying the name of a specific Certificate Server in the call to the Server Engine. For example, an organization might use a separate Certificate Authority (CA) for each division to provide flexibility over policies and key management. If this is the case, the enrollment code would then supply the name of the Certificate Server for the user's division when making the call to the Server Engine.

The IIS server has a series of HTML forms that allow the user to request certificate types if applicable and any identifying information that the CA needs in order to validate the request and generate the certificate.


Overview of Certificates and Authentication

Overview of Certificates and Authentication discusses digital certificates and how they are used for authentication. Some explanation of software security systems and cryptography is included to provide background on this subject.

Certificates are a form of digital identification used in software security systems to prove the identities of users on nonsecure networks such as the Internet. Certificates also provide the information necessary to conduct private communications and prove the origin of communications.

The term nonsecure network is used here to refer to a computer network that can be routinely accessed by users without the need to obtain access permission. Communications on such a network are subject to possible monitoring by unknown users. The potential also exists for fraudulent communications in which senders of messages falsely represent themselves.

Even private local area networks are vulnerable to determined efforts by intruders to acquire physical access to the network. Consequently, the existence of perfectly secure networks is nearly hypothetical. Nevertheless, on these secure networks a deliberate breach of privacy or misrepresentation of identity is an extraordinary occurrence. Therefore, we can conduct our network communications on them without security precautions because we can trust the other users on the network.

On a publicly accessible network such as the Internet, information may fall into the hands of users whose intentions are unknown. If the information has little or no value, then security measures may be unnecessary. If the information is valuable or confidential, then appropriate precautions should be implemented to secure the information.

This means ensuring that only individuals with whom we want to share the information can understand it, and people with whom we share the information are really the individuals chosen to share it. These two concerns are expressed by the terms privacy and authentication.

Privacy in this context depends upon the ability to prevent anyone except the intended recipient from being able to read a message — even though anyone on the network might be able to intercept it.

Authentication in this context is the verification that the entity with whom you are communicating is, in fact, who you think it is — even though you have no direct physical means of proof.

The need for privacy and authentication over nonsecure networks requires some form of data encryption and decryption, otherwise known as cryptography, as part of a software security system. Cryptographic protocols (a protocol is an agreed upon sequence of steps) employing certificates are designed to address these needs.


Cryptography

Cryptography provides a set of techniques for encrypting (scrambling) so data and messages are stored and transmitted securely. Cryptography can achieve secure communications even when the transmission medium (for example, the Internet) is not trustworthy. Cryptography can also encrypt sensitive files, so an intruder cannot understand them.

Cryptography also provides techniques for decrypting (unscrambling) encrypted data and messages to reveal the original state. Assuming the techniques are implemented properly, without knowledge of the secret cryptographic key necessary to decrypt a message, reconstruction of the original message is extremely difficult. Digital Envelope, an encryption method where only a particular recipient can decrypt a message, is an important cryptography technique.

Additionally, cryptography provides a set of techniques for verification of the origin of data and messages using Digital Signatures.

When using cryptography, the only part that must remain secret are the cryptographic keys, with the exception of keys known as public keys. Algorithms, key sizes, and file formats can be made public without compromising security.


Data Encryption

In using data encryption, a plaintext message can be scrambled to appear like random gibberish and be difficult to unscramble without a secret key. Here the term message refers to any piece of data designated for encryption. This message can be ASCII text, a database file, or any data designated for secure transmission. Plaintext refers to data that has not been encrypted, while ciphertext refers to data that is encrypted.

After a message has been encrypted, it can be stored on nonsecure media or transmitted on a nonsecure network, and still remain secret. Later, the message can be decrypted into its original form. This process is shown in the following illustration.

When a message is encrypted, an encryption key is used. This is analogous to a key used to lock a padlock. To decrypt the message, the corresponding decryption key must be used. It is very important to properly restrict access to the decryption key, because anyone who possesses it will be able to decrypt all messages that were encrypted with the matching encryption key.

Symmetric algorithms are the most common type of encryption algorithm. Symmetric algorithms use the same key for both encryption and decryption. In order to communicate using symmetric algorithms, both parties must share a secret key.

Public-key (asymmetric) algorithms use two different keys: a public key and a private key. The private key is kept private to the owner of the key pair, and the public key can be distributed to anyone who requests it (often through a certificate. If one key is used to encrypt a message, then the other key is required to decrypt the message.

Symmetric algorithms are much faster than public-key algorithms and are essential for encryption of large amounts of data. However, because the keys must remain secret, distribution of the keys to large numbers of people is not practical. Public-key algorithms solve this problem and can be used in conjunction with symmetric algorithms to achieve optimal performance when large amounts of data are involved.


Digital Signatures

Digital signatures can be used when a message is distributed in plaintext form, and the recipients should be able to verify that the message has not been tampered with by any unauthorized individual. Signing a message does not alter the message, it simply generates a digital signature string that is bundled with the message or transmitted separately.

Digital signatures can be generated using public-key signature algorithms where the transmitting party private key, used to generate the signature, is sent in an e-mail message. Upon receipt of the message, the recipient uses the distinct public key to validate the signature. Because only the signer's public key (received by the recepient in an earlier e-mail) can be used to validate the signature, the digital signature is proof that the message sender's identity is authentic. This process is shown in the following illustration.


Digital Envelopes

Digital envelopes are used to send private messages that can only be understood by a specific recipient. The method used is identical to that described in Data Encryption, with the additional provision that the message is encrypted using the recipient's public key. The message can then be decrypted only by using the recipient's private key, so only the recipient will be able to understand the message.


Authentication

An assumption has been made in the preceding sections discussing digital signatures and envelopes that the identity of the owner of the public key used to encrypt or decrypt a message is established beyond doubt. But in practice, how would recipients of a message purportedly sent by a party named "Alice", accompanied by a digital signature that can be validated with a public key purported to belong to Alice, be sure that they are really using Alice's public key? And similarly, how would the sender of a message in a digital envelope encrypted with a public key purported to belong to an intended recipient named "Bob" be sure that it is really Bob's public key?

The use of physical documents to achieve authentication in the real world has been in existence for a long time. For example, when you write a check for some purchase and the merchant asks to see your driver's license, the license is being used to increase the merchant's confidence that you are who the check indicates you are. In this case the merchant trusts that the state that issued you the license did an adequate job of verifying your identity. Another example is the use of a passport when traveling. The customs official who looks at your passport and then accepts it as proof of your identity, trusts that your government did an adequate job of identifying you before issuing you a passport. Notice that in both examples there has to be a level of trust in the certifying authority.

In order to guarantee authenticity of public keys, Microsoft® Certificate Server provides digital certificates (commonly known as certificates) as a secure method of exchanging public keys over a nonsecure network.


Digital Certificates

A certificate is a set of data that completely identifies an entity, and is issued by a Certificate Authority (CA) only after that authority has verified the entity's identity. The data set includes the public cryptographic key tendered to the entity. When the sender of a message signs the message with its private key, the recipient of the message can use the sender's public key (retrieved from the certificate either sent with the message or available elsewhere in the directory service) to verify that the sender is legitimate.

Digital certificates are virtual documents which authenticate individuals and entities on a network. The use of certificates on a network is more complex than the use of a physical document because the communicating parties most likely will not physically meet. Consequently, a method or protocol is necessary to attain a high level of trust despite the lack of physical verification. Additionally, on a nonsecure network it is much easier to intercept messages and present fictitious identities. To prevent these problems, security protocols employing the cryptographic techniques described in earlier topics make it very difficult, if not impossible, for someone to falsify a certificate and present a false identity.


Digital Certification

A primary goal of a digital certificate is to confirm that the public key contained in a certificate is the public key belonging to the person or entity to whom the certificate is issued. For example, a Certificate Authority (CA) may digitally sign a special message (known as certificate information) containing the name of a user (in this case "Alice,"), as well as her public key in such a way that anyone can verify that the certificate information message was signed by no one other than the CA. Thereby, trust in the public key designated for "Alice" is confirmed.

The typical implementation of digital certification involves a signature algorithm for signing the certificate. The process follows these steps:

  1. Alice sends a certificate request containing her name and public key to a CA.
  2. The CA creates a special message m from this request, which constitutes most of the certificate data. The CA signs the message with its private key and obtains a separate signature sig. The CA then returns the message m and the signature sig to Alice. Together, the two parts form a certificate.
  3. Alice sends the certificate to Bob which conveys trust in her public key.
  4. Bob verifies the signature sig using the CA public key. If the signature is verified, the public key designated for Alice is accepted.

As with any digital signature, anyone can verify, at any time, that the certificate was signed by the Certificate Authority (CA), without access to privileged information.

This scenario assumes that Bob knows the specific CA public key. The public key could be obtained from a copy of the CA certificate, which contains the public key.

Since certificates have a valid time duration, it is possible for the certificate to expire and no longer be valid. A certificate is valid only for the period of time specified by the CA that issued the certificate. The certificate contains information about the beginning and expiration dates. If a user attempts to obtain access to a secured server by using an expired certificate, server authentication software will automatically reject the access request. Users can renew certificates before the expiration date to avoid this situation.

It is also possible for certificates to be revoked by the CA for other reasons. To handle this situation, the CA maintains a list of revoked certificates. This list is called a certificate revocation list (CRL), and is available to network users to determine validity of any given certificate.


Certificate Authority Hierarchies

Within large organizations that are composed of small, multiple units, the need for each unit to manage their own resources on the corporate intranet is commonplace. Each unit must enforce the policies under which approval is granted to requesters to gain access to their intranet resources.

Providing these units the ability to set policies and issue certificates themselves can be accomplished by allowing them to become certifying authorities, each with their own Certificate Authority (CA) server. Proliferation of multiple CAs within an intranet should be monitored closely by the parent organization so no misuse of authority occurs.

Misuse of authority is addressed through use of a Certificate Authority (CA) hierarchy. The CA hierarchy begins with an ultimate certifying authority called root. The root authority certifies CA servers within the parent organization to enforce security and control throughout the entire system. In large organizations, there may be multiple tiers of CA servers so the hierarchy can be deployed throughout all the units in the parent organization. For example, a first-tier CA would be certified by the root CA, and would then certify a second-tier CA, as shown in the following diagram.

The use of a CA hierarchy provides large organizations with the flexibility needed to manage policies and grant certificates throughout a certification system composed of multiple certificate authorities. A CA hierarchy enables a certification system to be managed from a single control point. For example, the root authority could employ hardware-based key management so a specific, subordinate CA is certified under the greatest possible security.

When a certificate issued by a Tier-1 or Tier-2 CA is transmitted on a network, the recipient must verify that the issuing CA has been certified by the level above it, and that the one at that level has been certified by the one above it, until a chain of authority exists between the lower-level CA and the Root CA. For example, in the preceding diagram, it could be verified that CA #4 was certified by CA #1 and that CA #1 was certified by Root CA.

If for some reason a lower-level CA mismanages the issuance of certificates, the relevant server certificate can be revoked by the root authority. This effectively invalidates certificates issued by the lower-level CA without affecting any other certificates issued within the parent organization.


Supported Certificate Formats

Microsoft® Certificate Server has the ability to issue the following types of certificates:

  • X.509 v1 and v3 SSL-compatible client authentication certificate. This client authentication certificate identifies a client and is used by servers to authenticate a client that requests server access.
  • X.509 v3 SSL-compatible server authentication certificate. This server authentication certificate identifies a server and is used by clients to authenticate a server that the client wants to access.
  • S/MIME certificate. This certificate is used by clients for secure e-mail under the S/MIME (Secure/Multipurpose Internet Mail Extensions) protocol.
  • In addition to these certificates, Certificate Server can also be used to issue other X.509 certificates such as SET (Secure Electronic Transacation) certificates by writing a custom policy module.

    Note "Server authentication certificate" and "server certificate" as well as "client authentication certificate" and "client certificate" are interchangeable terms.


Guidelines for Distinguished Name Fields

A certificate request contains information that should uniquely identify the individual making the request.

PKCS #10 format certificate requests that are accepted by Microsoft® Certificate Server contain identification fields that are referred to as Distinguished Name (DN) fields. These fields will contain the information that is input by the user when a certificate request is being created by Key Manager or some other means.

The following are some guidelines for completion of DN fields in a certificate request:

Field | Description
Common Name | In the Common Name field you should enter the fully qualified hostname/path used in DNS lookups that the server will be running on (for example, hostname.thecompany.com).
Organization | The Organization Name you specify should be the legal name for your organization. that is registered with the appropriate state, country or city authority. The legal name of the organization must be used in the Organization field.
Organizational Unit | The Organizational Unit field can be used to differentiate between different divisions within an organization, for example "Internet Security Unit" or "Human Resources." This field is also recommended to be used for specifying a DBA (Doing Business As...) value.
Locality | The Locality field denotes the city that the organization resides in. If the organization has local standing only, by virtue of having a business license registered with the City Clerk for the City of Cambridge in the State of Massachusetts, then the Locality field must contain Cambridge.
State or Province | The State or Province field specifies where the organization is physically located. If your organization is incorporated in Delaware but has a DBA (Doing Business As...) within California, use California. The State or Province field should not be an abbreviated field. For example, "CA" is not a valid state name. "California" is the proper state name.
Country | The X.500 Naming Scheme standard requires a 2-character country code. The country code for the United States is US; the code for Canada is CA.


Glossary of Terms

The following table provides explanations of acronyms and other technical terms that appear throughout the Microsoft® Certificate Server documentation set.

Term | Description
ASN.1 | Abstract Syntax Notation One. A data definition language.
CA | Certificate Authority. An entity that issues, manages and revokes certificates.
CA certificate | Identifies the Certificate Authority (CA) that issues server and/or client authentication certificates to the servers and clients that request these certificates. Because it contains a public key used in digital signatures, it is also referred to as a signature certificate. If the CA is a root authority, the CA certificate may be referred to as a root certificate. Also sometimes known as a site certificate.
CA hierarchy | A Certificate Authority (CA) hierarchy contains multiple CAs. It is organized such that each CA is certified by another CA in a higher level of the hierarchy until the top of the hierarchy, also known as the root authority, is reached.
client certificate | Refers to a certificate used for client authentication, such as authenticating a Web browser on a Web server. When a Web browser client attempts to access a secured Web server, the client sends its certificate to the server to allow it to verify the client's identity.
CRL | Certificate revocation list. A document maintained and published by a CA that lists certificates that have been revoked by the CA.
CryptoAPI | Microsoft Cryptographic API. An application programming interface providing services for authentication, encoding, and encryption in Microsoft Win32®-based applications.
CSP | Cryptographic Service Provider. The code that actually performs authentication, encoding and encryption services accessed by Win32-based applications through the CryptoAPI.
DLL | Dynamic-link library. A code module that is not itself an executable program, but can be loaded and shared by one or more executable programs.
key exchange certificate | Certificate used to encrypt information sent to another party. The Certificate Authority (CA) key exchange certificate can be used by a client to encrypt information sent to the CA.
IIS | Microsoft Internet Information Server.
LDAP | Lightweight Directory Access Protocol. A more easily implemented subset of the X.500 DAP standard for directory services.
MD2 | Message digest algorithm.
MD4 | Message digest algorithm.
MD5 | Message digest algorithm.
message digest | A short, fixed-length digital string derived from a longer, variable-length message using a computational algorithm.
PKCS | Public-Key Cryptography Standards.
root authority | The Certificate Authority (CA) at the top of a CA hierarchy. Certifies CAs in the next level of the hierarchy.
root certificate | A self-signed Certificate Authority (CA) certificate that identifies a CA. It is called a root certificate because it is the certificate for the root CA. The root CA must sign its own CA certificate because by definition there is no higher certifying authority to sign its CA certificate.
RPC | Remote Procedure Calls. A widely used standard defined by the Open Software Foundation (OSF) for distributed computing. The RPC transport enables one process to make calls to functions that are part of another process. The other process can be on the same computer or on a different computer on the network.
server certificate | Refers to a certificate used for server authentication, such as authenticating a Web server to a Web browser. When a Web browser client attempts to access a secured Web server, the server sends its certificate to the browser to allow it to verify the server's identity.
SET | Secure Electronic Transaction. A protocol for secure electronic transactions over the Internet.
SHA | Secure Hash Algorithm. A message digest algorithm.
signature certificate | A certificate containing a public key that is used to verify digital signatures.
site certificate | Both server certificates and Certificate Authority (CA) certificates are sometimes called site certificates. When referring to a server certificate, the certificate identifies the Web server presenting the certificate. When referring to a CA certificate, the certificate identifies the CA that issues server and/or client authentication certificates to the servers and clients that request these certificates.
S/MIME | Secure/Multipurpose Internet Mail Extensions. A protocol for secure electronic mail over the Internet.
SSL | Secure Sockets Layer. A protocol for secure network communications using a combination of public and secret key technology.
URL | Uniform Resource Locator. An encoding scheme used by the World Wide Web (WWW) for accessing data on the Internet. The general format is service://hostname/pathname.
X.509 | Standard certificate format supported by Certificate Server.


Further Reading About Public Key and Cryptography

The following discuss certificates, authentication, and associated security issues:

  • Information about Public-Key Cryptography Standards (PKCS) and other cryptography standards: http://www.rsa.com
  • Schneier, Bruce. Applied Cryptography, 2d ed. New York: John Wiley & Sons, 1996.
  • Consultation Committee, International Telephone and Telegraph (CCITT), CCITT, Recommendation X.509, The Directory-Authentication Framework, International Telecommunications Union, Geneva, 1989.
  • For information about Microsoft® Internet Security Framework, Microsoft CryptoAPI, and other Microsoft security technologies: at http://www.microsoft.com/security


Using the Certificate Server Programmer's Reference

Developers using the Certificate Server Programmer's Reference should first become familiar with the Certificate Server architecture and theory of operation as discussed in Certificate Server Concepts. Portions of this material assume that the reader has a basic familiarity with public-key cryptography, digital certificates, and authentication. Readers who are new to these topics are advised to read Overview of Certificates and Authentication in Certificate Server Concepts before proceeding.

For explanations of acronyms and other technical terms, please refer to the Glossary of Terms.

Note The Certificate Server Release Notes contain important additional information about Certificate Server's programmable interfaces and may contain corrections to errors in this documentation release. The Certificate Server Release Notes are located in the Microsoft Windows NT 4.0 Option Pack documentation under Getting Started.

For further information about using the Certificate Server Programmer's Reference, see the following topics:

  • Documentation Conventions
  • Interface Documentation


Documentation Conventions

This document uses the following document conventions.

Style | Used For
Bold | Literal values such as command-line commands and options, menu options, dialog box names, and user interface labels.
Italic | "Placeholder" values, such as generic variable names in function or command syntax. Also used for general emphasis.
Monospace | Examples of code or screen output, and user-defined variable names.


Interface Documentation

For each interface a general description is provided and then the interface's methods are described. For each method, the syntax for all three languages: Microsoft® Visual Basic®, Java, and C++, is shown. The format of the method descriptions resembles C/C++ function prototypes, and is used uniformly for all languages to present information about the calling syntax. The symbols [VB], [JAVA], and [C++] are shown beside each item to indicate which language uses that particular syntax. Any items that have no symbols beside them pertain to all three languages.


Programming Certificate Server

This topic section discusses the following:

  • Certificate Server Development Files
  • Data Types Used by Certificate Server Interfaces
  • Using Return Values in C/C++, Microsoft Visual Basic, and Java
  • Error Checking in C/C++, Microsoft Visual Basic, and Java
  • IDispatch Support


Development Files

The following sample code is included for developing with Microsoft® Certificate Server:

  • Sample Microsoft Visual Basic® 5.0 policy module, located in the \policyvb subdirectory of the SDK files.
  • Source code for the default Microsoft Visual C++® policy module, located in the \policy subdirectory of the SDK files.
  • Source code for the default Microsoft Visual C++® extension handler, located in the \encode subdirectory of the SDK files.
  • Sample Microsoft Visual C++ exit module, located in the \certexit subdirectory of the SDK files.
  • Certificate Server include (.H) files, located in the \inc subdirectory of the SDK files.
  • Certificate Server library (.LIB) and type library (.TLB) files for the X86 platform, located in the \lib\i386 subdirectory of the SDK files.


Data Types

The following data types are used by Microsoft® Certificate Server interface methods.

Microsoft Visual Basic® | Java | C++
int | short | ---
long | int | LONG
BSTR | java.lang.String | BSTR
DATE | double | DATE
VARIANT | com.ms.Variant | VARIANT

VARIANT type variables have a type tag field vt that indicates the data type of the data. VARIANT type return values are returned by methods with the type tag field set to the data type of the return value. VARIANT type input parameters in a method call must have the type tag field set by the application to one of the supported values. The correspondence of parameter types to data types is as follows.

Parameter Type | Data Type
PROPTYPE_LONG | VT_I2 or VT_I4
PROPTYPE_DATE | VT_DATE
PROPTYPE_BINARY | VT_BSTR or (VT_BSTR | VT_BYREF)
PROPTYPE_STRING | VT_BSTR or (VT_BSTR | VT_BYREF)

The following example written in C++ shows how the type tag field could be initialized for a call to the ICertServerPolicy::SetCertificateExtension method:

HRESULT hr;
BSTR strExtensionName = SysAllocString("2.29.38.4");
VARIANT varExt;
varExt.vt = VT_BSTR;    // initialize type tag field
varExt.bstrVal = SysAllocString("http://UrlTest.htm");

hr = pICertServerPolicy->SetCertificateExtension(
    strExtensionName,      // extension name
    PROPTYPE_STRING,
    EXTENSION_CRITICAL_FLAG,
    &varExt);

// Use the strAttributeValue ...

// free it when done
if (NULL != strExtensionName)
{
    SysFreeString(strExtensionName);
}
VariantClear(&varExt);


Method Return Values

For each interface method there are three prototypes shown, each of which has the [VB], [JAVA], or [C++] notation beside it. In most cases the method prototypes return different values, depending on which language is being used.

Return Values For Microsoft Visual Basic

The return value is usually handled by a variant data structure that will automatically handle whatever type is returned. A method call would be as follows:

Dim AttributeValue As VARIANT  'return value

AttributeValue = GetRequestAttribute("TheAttribute")

In this example code fragment, the return variable AttributeValue would be accepting a VT_BSTR type.

Return Values For Java

The return type will be of one of the java.lang.XXX class types; such as java.lang.String, or com.ms.Variant. A method call would be as follows:

com.ms.Variant    AttributeValue;  // return value

AttributeValue = GetRequestAttribute("TheAttribute");

In this example code fragment, the variable AttributeValue would be accepting a com.ms.Variant type.

Return Values For Microsoft C++

The return value is always of type HRESULT, and it is from this return value that it can be determined whether the method succeeded or not, and if not, what the error was. Programmatic values that need to be returned are returned through "output" parameters in the method. The following example shows a C++ method call to retrieve a request attribute:

HRESULT hr;
BSTR strAttributeName = SysAllocString("TheAttribute");
BSTR strAttributeValue = SysAllocStringByteLen("", 49);

hr = pICertServerPolicy->GetRequestAttribute(
                                strAttributeName,
                                &strAttributeValue);
HRESULT hr;
BSTR strAttributeName = SysAllocString("TheAttribute");
BSTR strAttributeValue = NULL;

hr = pICertServerPolicy->GetRequestAttribute(
                                strAttributeName,
                                &strAttributeValue);

// Use strAttributeValue ...

// then free it when done
if (NULL != strAttributeName)
{
    SysFreeString(strAttributeName);
}
if (NULL != strAttributeValue)
{
    SysFreeString(strAttributeValue);
}

In the preceding code fragment, success or failure is returned to the "hr" variable. The request attribute value is a string returned in the BSTR strAttributeValue parameter.


Error Checking

In the case of both Microsoft® Visual Basic® and Java, if an error occurs within the method, the method will throw an exception. The script or program must check for these exceptions separately from the return value.

For C++, the return value is always an HRESULT, and indicates whether the method call succeeded or failed. If the call failed then the return value indicates why it failed.

Error Checking For Microsoft Visual Basic

Microsoft® Visual Basic® VBScript uses the Err object's Number property to check for errors, as shown in the example code that follows.

The properties of the Err object are set by the generator of an error — Visual Basic, an OLE object, or the Visual Basic programmer. The default property of the Err object is Number. Err.Number contains an integer and can be used by an Automation object to return an SCode.

When a run-time error occurs, the properties of the Err object are filled with information that uniquely identifies the error and information that can be used to handle it. To generate a run-time error in your code, use the Raise method.

The Err object's properties are reset to zero or zero-length strings ("") after a On Error Resume Next statement and after an Exit Sub or Exit Function statement within an error-handling routine. The Clear method can be used to explicitly reset Err.

The Err object is an intrinsic object with global scope — there is no need to create an instance of it in your code. The following is an example using a function from the Microsoft® CryptoAPI 2.0:

Set CertObj = StoreObj.FindCertificate(0, 0, &H50000, _
                BlobApi.I4ToBlobString(2), Nothing, CertObj)
            If err.Number <> 0 Then
                If err.Number <> &H80092111 Then
                    MyWriteLn "FindCertificate err = " &Hex(err.Number)
                End If
                GetSignCert = Null
                MyWriteLn "No Signer Cert"
                Exit Function
            End If

Error Checking For Java

ComFailException indicates a failure. The exception object wraps an HRESULT, the return type for most methods in the Component Object Model (COM). The default value of the HRESULT stored in a ComFailException is E_FAIL (0x80004005L). All failure HRESULTs have their most significant bit set.

The values of system-defined HRESULTs can be found in WINERROR.H, included with the Microsoft® Platform SDK. For object specific errors, see the documentation associated with the object.

For system-defined errors, the detail message stored in the ComException object is the string returned by the Microsoft Win32® API function FormatMessage, which returns a brief message associated with the error. This detail message can be retrieved by calling getMessage (defined by the Throwable class).

The following code is an example of testing the ComFailException using a function from the Microsoft® CryptoAPI 2.0:

try {
    certObj = (ICertificate) storeObj.FindCertificate(0, 0,
        0x50000,  blobApi.I4ToBlobString(2), null, certObj);
} catch (ComFailException e) {
    if (e.getHResult() != 0x80092111)
        TextIO.writeLn("FindCertificate err = " +
            TextIO.toUString(e.getHResult()));
    TextIO.writeLn("No Signer Cert");
    return null;
}

Error Checking For C++

C++ directly returns HRESULT values that can be used for error checking, as the following code fragment demonstrates. For example error codes, see the list of error codes in the "Common HRESULT Values" section that follows.

HRESULT hr;
BSTR strAttributeName = SysAllocString("TheAttribute");
BSTR strAttributeValue = SysAllocStringByteLen("", 49);

hr = pICertServerPolicy->GetRequestAttribute(
                                strAttributeName,
                                &strAttributeValue);
if(S_OK != hr)          // If the function failed…
{
    if(E_INVALIDARG == hr);
            ; // Do something
}

Common HRESULT Values

The following table lists the values of common HRESULT values.

Name | Description | Value
S_OK | Operation successful | 0x00000000
E_UNEXPECTED | Unexpected failure | 0x8000FFFF
E_NOTIMPL | Not implemented | 0x80004001
E_OUTOFMEMORY | Failed to allocate necessary memory | 0x8007000E
E_INVALIDARG | One or more arguments are invalid | 0x80070057
E_NOINTERFACE | No such interface supported | 0x80004002
E_POINTER | Invalid pointer | 0x80004003
E_HANDLE | Invalid handle | 0x80070006
E_ABORT | Operation aborted | 0x80004004
E_FAIL | Unspecified failure | 0x80004005
E_ACCESSDENIED | General access denied error | 0x80070005
E_NOTIMPL | Not implemented | 0x80000001


IDispatch Support

The Microsoft® Certificate Server interfaces include direct COM and IDispatch support. However, only Microsoft Visual Basic® and Java applications should attempt to use the IDispatch support. C++ applications should always use the direct COM interfaces.


Certificate Server Development Architecture

Microsoft® Certificate Server is a development platform for building Certificate Authorities for enterprises or secure Internet applications. A configured and operational Certificate Authority will allow a site to issue, track, manage, and revoke certificates with minimal administration overhead and maximal security.

The Certificate Server consists of the Server Engine, the Server Database, and a set of modules and tools that work together to function as a Certificate Authority. External applications, modules, and administration tools use Component Object Model (COM) interfaces to interact with the Server Engine. The following diagram shows the interfaces used by the Server Engine:

An operational certification system will typically have four major subsystems.

Client | The client is the software that is used by the end user to generate a certificate request, send the request, and receive the finished certificate. An example of a client is Microsoft® Internet Explorer version 3.0. The client will typically interact with a custom interface maintained by the intermediary application.
Intermediary | The intermediary is a sub-system that consists of the intermediary application and the Certificate Server Client Interface (Certificate Server Web Client in the setup program). The intermediary application interacts directly with the client, receiving certificate requests and returning finished certificates. It communicates with the Server Engine through the Certificate Server Client Interface, which contains the ICertConfig and ICertReqest COM interfaces. An example of an intermediary application is Microsoft Internet Information Server. The intermediary application can be implemented entirely through Active Server Pages.
Server | The server is the system that builds the certificate. In addition to the Server Engine, two configurable components are included; the policy module and the exit module. The policy module interacts with the Server Engine through the ICertPolicy and ICertServerPolicy interfaces. Exit modules (there can be more than one) interact with the Server Engine through the ICertExit and ICertServerExit interfaces.
Administrative Client | The administrative client is the system that monitors and manages certificates and requests. The administrative client uses the ICertAdmin interface to communicate with the Server Engine.

For further information about the Certificate Server architecture, see Certificate Server Interfaces and Building a Certificate.


Certificate Server Interfaces

The following interfaces are exported by the Server Engine and are called by external objects.

ICertConfig | Used by clients to get information about a server.
ICertRequest | Used to send a request to the server and get the results of the request.
ICertAdmin | Used by administration programs to manage requests, certificates, and revocation.
ICertServerPolicy | Used by the policy module to get and set certificate and request properties.
ICertServerExit | Used by exit modules to get and set certificate and request properties.
ICertView | Used by clients to view the Certificate Server database.
IEnumCERTVIEWATTRIBUTE | Used by clients to access the certificate attributes for a row in the Certificate Server view.
IEnumCERTVIEWCOLUMN | Used by clients to access the data columns of a row in the Certificate Server view.
IEnumCERTVIEWEXTENSION | Used by clients to access the certificate extension data for a row in the Certificate Server view.
IEnumCERTVIEWROW | Used by clients to enumerate the rows of the Certificate Server view.

The following interfaces are imported by the Server Engine.

ICertExit | Exported by exit modules. Used by the Server Engine to deliver finished certificates and revocation information.
ICertPolicy | Exported by the policy module. Used by the Server Engine to check requests and get properties for certificates.

The following interfaces can be exported by extension handlers and are imported by the policy module.

ICertEncodeAltName | Used by the policy module to handle alternate name arrays used in certificate extensions.
ICertEncodeBitString | Used by the policy module to handle bit strings used in certificate extensions.
ICertEncodeCRLDistInfo | Used by the policy module to handle CRL distribution information arrays used in certificate extensions.
ICertEncodeDateArray | Used by the policy module to handle date arrays used in certificate extensions.
ICertEncodeLongArray | Used by the policy module to handle long arrays used in certificate extensions.
ICertEncodeSampleStructure1 | Sample interface demonstrating how to handle a custom structure used in certificate extensions.
ICertEncodeSampleStructure2 | Sample interface demonstrating how to handle a custom structure used in certificate extensions.
ICertEncodeStringArray | Used by the policy module to handle string arrays used in certificate extensions.


Building a Certificate

To build a certificate, the following call order will occur:

  1. Certificate Authority (CA) initializes modules through calls to ICertPolicy and ICertExit (happens once on server initialization). The CA will initialize the policy and exit modules by calling ICertPolicy::Initialize and ICertExit::Initialize.
  2. Intermediary to CA through ICertConfig (happens once per intermediary init). The intermediary finds the needed configuration string by calling ICertConfig::GetConfig.
  3. Client to intermediary through unknown (happens once per request). The client sends a certificate request to the intermediary. This can be, for example, Microsoft® Internet Explorer sending a request through CertEnroll.dll to Microsoft Internet Information Server.
  4. Intermediary to CA through ICertRequest (happens once per request). The intermediary sends the certificate request to the CA through ICertRequest::Submit. In the case of Internet Information Server, this could be done through Active Server Page scripts.
  5. CA calls Policy Module through ICertPolicy (happens once per request). The CA notifies the policy module that a request has arrived by calling ICertPolicy::VerifyRequest. The policy module can indicate that the request is OK, the request is to be denied, or the request should be suspended. If the request is suspended, the admin must resubmit the request.
  6. Admin calls CA through ICertAdmin. If the request is suspended, the admin can resubmit the request.
  7. Policy Module modifies the certificate through ICertServerPolicy (optional). The policy module can examine the request and change the certificate by calling methods of ICertServerPolicy. The certificate is built at this point.
  8. CA calls Exit Module through ICertExit. If the exit module indicated that it is interested in seeing certificates issued (when the CA called ICertExit::Initialize), the CA will call ICertExit::Notify.
  9. Exit module calls the CA through ICertServerExit. The exit module can examine the request and the new certificate by calling methods of ICertServerExit.


ICertAdmin Interface

The ICertAdmin interface allows properly authorized clients to perform the following actions:

  • Authorize or deny a certificate request.
  • Revoke an issued certificate.
  • Trigger the generation of a certificate revocation list (CRL).
  • Get the current CRL for the server.

ICertAdmin callers have write-only access to request attributes and certificate extensions, but no direct access to other request and certificate properties.

The following methods are provided by the ICertAdmin interface.

Method | Description
DenyRequest | Denies a specified request.
GetCRL | Gets a pointer to the current certificate revocation list (CRL).
GetRevocationReason | Returns a human-readable string specifying the reason a certificate was revoked.
IsValidCertificate | Checks the validity of a certificate.
PublishCRL | Publishes a new certificate revocation list.
ResubmitRequest | Submits the specified request back to the policy module .
RevokeCertificate | Revokes a certificate by a specified date.
SetCertificateExtension | Adds a new extension to the certificate to be issued.
SetRequestAttributes | Sets attributes in the specified request.


ICertAdmin::DenyRequest

The DenyRequest method denies a specified request.

[VB] void DenyRequest(
  BSTR strConfig,
  long RequestId
);

[JAVA] void DenyRequest(
  java.lang.String strConfig,
  int RequestId
);

[C++] HRESULT DenyRequest(
  BSTR const strConfig,  // in
  LONG RequestId         // in
);

Parameters

[VB][JAVA][C++] strConfig
Points to a valid configuration string for the certificate server. See ICertConfig::GetConfig.
[VB][JAVA][C++] RequestId
Specifies the ID of the request to be denied.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certadm.h.
Import Library: Use certidl.lib.


ICertAdmin::GetCRL

The GetCRL method gets a pointer to the current certificate revocation list (CRL) for the certificate server.

[VB] BSTR GetCRL(
  BSTR strConfig,
  long Flags
);

[JAVA] java.lang.String GetCRL(
  java.lang.String strConfig,
  int Flags
);

[C++] HRESULT GetCRL(
  BSTR const strConfig,  // in
  LONG Flags,            // in
  BSTR *pstrCRL          // out, return value
);

Parameters

[VB][JAVA][C++] strConfig
Points to a valid configuration string for the certificate server. See ICertConfig::GetConfig.
[VB][JAVA][C++] Flags
Specifies the format of the returned CRL. The value can be one of the following values.
CRL Format Flag | Description
CR_OUT_BASE64HEADER | BASE64 format with begin/end.
CR_OUT_BASE64 | BASE64 format without begin/end.
CR_OUT_BINARY | Binary format.

[C++] pstrCRL
Points to the return value. See Return Values.

Return Values

Returns the CRL.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certadm.h.
Import Library: Use certidl.lib.


ICertAdmin::GetRevocationReason

The GetRevocationReason method returns a human-readable string specifying the reason a certificate was revoked. This call must be preceded by a successful IsValidCertificate method call.

[VB] Long GetRevocationReason(void);

[JAVA] int GetRevocationReason(void);

[C++] HRESULT GetRevocationReason(
  LONG *pReason    // out, return value
);

Parameters

[C++] pReason
Points to the return value. See Return Values.

Return Values

Returns a value specifying the reason the certificate was revoked. The value can be one of the following values (defined in WinCrypt.h).

Revocation Reason | Value
CRL_REASON_UNSPECIFIED | 0
CRL_REASON_KEY_COMPROMISE | 1
CRL_REASON_CA_COMPROMISE | 2
CRL_REASON_AFFILIATION_CHANGED | 3
CRL_REASON_SUPERSEDED | 4
CRL_REASON_CESSATION_OF_OPERATION | 5
CRL_REASON_CERTIFICATE_HOLD | 6

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certadm.h.
Import Library: Use certidl.lib.


ICertAdmin::IsValidCertificate

The IsValidCertificate method checks the validity of a certificate. The validity is checked by verifying the certificate against the CA key, and then checking that the certificate has not been revoked.

[VB] long IsValidCertificate(
  BSTR strConfig,
  BSTR strSerialNumber
);

[JAVA] int IsValidCertificate(
  java.lang.String strConfig,
  java.lang.String strSerialNumber
);

[C++] HRESULT IsValidCertificate(
  BSTR const strConfig,        // in
  BSTR const strSerialNumber,  // in
  LONG *pDisposition           // out, return value
);

Parameters

[VB][JAVA][C++] strConfig
Points to a valid configuration string for the certificate server. See ICertConfig::GetConfig.
[VB][JAVA][C++] strSerialNumber
Specifies the serial number identifying the certificate to be reviewed. The string must specify the serial number as an even number of hexadecimal digits. If necessary, a zero may be prepended to the number to achieve an even number of digits. No more than one leading zero may be used.
[C++] pDisposition
Points to the return value. See Return Values.

Return Values

Returns a value specifying the disposition of the certificate. The following are possible values that specify the disposition.

Name | Description
CA_DISP_INCOMPLETE | Call did not complete
CA_DISP_ERROR | Call failed
CA_DISP_REVOKED | Certificate revoked
CA_DISP_VALID | Certificate still valid
CA_DISP_INVALID | Certificate never issued
CA_DISP_UNDER_SUBMISSION | Taken under submission

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certadm.h.
Import Library: Use certidl.lib.


ICertAdmin::PublishCRL

The PublishCRL method causes the certificate server to publish a new certificate revocation list (CRL.)

[VB] void PublishCRL(
  BSTR strConfig,
  DATE Date
);

[JAVA] void PublishCRL(
  java.lang.String strConfig,
  double Date
);

[C++] HRESULT PublishCRL(
  BSTR const strConfig,  // in
  DATE Date              // in
);

Parameters

[VB][JAVA][C++] strConfig
Points to a valid configuration string for the certificate server. See ICertConfig::GetConfig.
[VB][JAVA][C++] Date
Specifies the expiration date of the CRL, in GMT time.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certadm.h.
Import Library: Use certidl.lib.


ICertAdmin::ResubmitRequest

The ResubmitRequest method submits the specified request back to the policy module for the specified certificate server.

[VB] Long ResubmitRequest(
  BSTR strConfig,
  long RequestId
);

[JAVA] int ResubmitRequest(
  java.lang.String strConfig,
  int RequestId
);

[C++] HRESULT ResubmitRequest(
  BSTR const strConfig,  // in
  LONG RequestId,        // in
  LONG * pDisposition    // out, return value
);

Parameters

[VB][JAVA][C++] strConfig
Points to a valid configuration string for the certificate server. See ICertConfig::GetConfig.
[VB][JAVA][C++] RequestId
Specifies the ID of the request to resubmit.
[C++] pDisposition
Points to the return value. See Return Values.

Return Values

Returns a value specifying the disposition of the request. See return values listed for the ICertRequest::Submit method.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certadm.h.
Import Library: Use certidl.lib.


ICertAdmin::RevokeCertificate

The RevokeCertificate method revokes a certificate by a specified date.

[VB] void RevokeCertificate(
  BSTR strConfig,
  BSTR strSerialNumber,
  long Reason,
  DATE Date
);

[JAVA] void RevokeCertificate(
  java.lang.String strConfig,
  java.lang.String strSerialNumber,
  int Reason,
  double Date
);

[C++] HRESULT RevokeCertificate(
  BSTR const strConfig,        // in
  BSTR const strSerialNumber,  // in
  LONG Reason,                 // in
  DATE Date                    // in
);

Parameters

[VB][JAVA][C++] strConfig
Points to a valid configuration string for the certificate server. See ICertConfig::GetConfig.
[VB][JAVA][C++] strSerialNumber
Specifies the serial number identifying the certificate to be revoked. The string must specify the serial number as an even number of hexadecimal digits. If necessary, a zero may be prepended to the number to achieve an even number of digits. No more than one leading zero may be used.
[VB][JAVA][C++] Reason
Specifies the reason for the revocation. The value can be one of the following values (defined in WinCrypt.h).
Revocation Reason | Value
CRL_REASON_UNSPECIFIED | 0
CRL_REASON_KEY_COMPROMISE | 1
CRL_REASON_CA_COMPROMISE | 2
CRL_REASON_AFFILIATION_CHANGED | 3
CRL_REASON_SUPERSEDED | 4
CRL_REASON_CESSATION_OF_OPERATION | 5
CRL_REASON_CERTIFICATE_HOLD | 6

[VB][JAVA][C++] Date
Specifies the date at which the revocation will become effective, in GMT time. The value 0 indicates that the current GMT time should be used.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certadm.h.
Import Library: Use certidl.lib.


ICertAdmin::SetCertificateExtension

The SetCertificateExtension method adds a new extension to the certificate to be issued.

[VB] void SetCertificateExtension(
  BSTR strConfig,
  long RequestId,
  BSTR strExtensionName,
  long Type,
  long Flags,
  VARIANT pvarValue
);

[JAVA] void SetCertificateExtension(
  java.lang.String strConfig,
  int RequestId,
  java.lang.String strExtensionName,
  int Type,
  int Flags,
  com.ms.Variant pvarValue
);

[C++] HRESULT SetCertificateExtension(
  BSTR const strConfig,         // in
  LONG RequestId,               // in
  BSTR const strExtensionName,  // in
  LONG Type,                    // in
  LONG Flags,                   // in
  VARIANT const *pvarValue      // in
);

Parameters

[VB][JAVA][C++] strConfig
Points to a valid configuration string for the certificate server. See ICertConfig::GetConfig.
[VB][JAVA][C++] RequestId
Specifies the ID of the request to resubmit.
[VB][JAVA][C++] strExtensionName
Specifies the Object ID (OID) for the extension to set. In this release the string must be 31 or less non-null characters in length.
[VB][JAVA][C++] Type
Specifies the type of extension being set. The Type parameter must agree with the data type of pvarValue that is set in the vt field of the VARIANT structure. See Data Types. The Type parameter can be set to one of the following.
Type | Description
PROPTYPE_LONG | Signed long data
PROPTYPE_DATE | Date / Time
PROPTYPE_BINARY | Binary data
PROPTYPE_STRING | String data

[VB][JAVA][C++] Flags
Specifies the flags for the extension being set. Use a value of 0 if no flag is to be set, or one of the following flag values.
Flag Value | Explanation
EXTENSION_CRITICAL_FLAG | This is a critical extension
EXTENSION_DISABLE_FLAG | Extension will not be used

Note When ExtFlags is set to EXTENSION_DISABLE_FLAG, the extension will be disabled in the Server Log but will not be added to the certificate.

[VB][JAVA][C++] pvarValue
Specifies the value associated with the extension.

Return Values

This method does not return a value.

Comments

The following C++ code sets a revocation URL string and extension critical flag into the certificate:

HRESULT hr;
BSTR strExtensionName = SysAllocString("2.29.38.4");
VARIANT varExt;
varExt.vt = VT_BSTR;    // initialize type tag field
varExt.bstrVal = SysAllocString("http://UrlTest.htm");

hr = pICertServerPolicy->SetCertificateExtension(
    strConfig,             // assume previously set
    RequestId,             // assume previously set
    strExtensionName,      // extension name
    PROPTYPE_STRING,
    EXTENSION_CRITICAL_FLAG,
    &varExt);

// Use the strAttributeValue ...

// free it when done
if (NULL != strExtensionName)
{
    SysFreeString(strExtensionName);
}
VariantClear(&varExt);

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certadm.h.
Import Library: Use certidl.lib.


ICertAdmin::SetRequestAttributes

The SetRequestAttributes method sets attributes in the specified request.

[VB] void SetRequestAttributes(
  BSTR strConfig,
  long RequestId,
  BSTR strAttributes
);

[JAVA] void SetRequestAttributes(
  java.lang.String strConfig,
  int RequestId,
  java.lang.String strAttributes
);

  BSTR const strConfig,      // in
  LONG RequestId,            // in
  BSTR const strAttributes   // in
);

Parameters

[VB][JAVA][C++] strConfig
Points to a valid configuration string for the certificate server. See ICertConfig::GetConfig.
[VB][JAVA][C++] RequestId
Specifies the ID of the request to set attributes for.
[VB][JAVA][C++] strAttributes
Specifies the attribute data. The literal string "\n" separates multiple attributes. There is no set limit to the number of request attributes may be added to a request.

Note In the current release, attribute names and values each must be 49 or less non-null characters in length.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certadm.h.
Import Library: Use certidl.lib.


ICertConfig Interface

The ICertConfig interface is used to gather configuration information about the certificate servers available in a given installation. ICertConfig provides methods to examine the public configuration point specified during client setup. Any server setup to post its configuration information to this public configuration point will be visible to ICertConfig. Client programs can use ICertConfig to get the following information:

  • The set of servers in the enterprise.
  • The details of a specific configuration.
  • The default server in the enterprise.

The following methods are provided by the ICertConfig interface.

Method | Description
GetConfig | Gets the default configuration string for the certificate server.
GetField | Gets a specific field from the current record of the configuration database.
Next | Points to the next available certificate server configuration in the configuration point.
Reset | Resets the configuration query state.


ICertConfig::GetConfig

The GetConfig method gets the default configuration string for the certificate server. The configuration string is the server name and subname separated by a slash. This configuration string can be used to refer unambiguously to a specific certificate server. Note that this may prompt the user to select the server that they wish to use. (Future functionality.)

[VB] BSTR GetConfig(
  long Flags
);

[JAVA] java.lang.String GetConfig(
  int Flags
);

[C++] HRESULT GetConfig(
  LONG Flags,     // in
  BSTR *pstrOut   // out, return value
);

Parameters

[VB][JAVA][C++] Flags
Optional flags (undefined).
[C++] pstrOut
Points to the return value. See Return Values.

Return Values

Returns a string specifying the default configuration.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certcli.h.
Import Library: Use certidl.lib.


ICertConfig::GetField

The GetField method gets a specific field from the current record of the configuration database.

[VB] BSTR GetField(
  BSTR strFieldName
);

[JAVA] java.lang.String GetField(
  BSTR strFieldName
);

[C++] HRESULT GetField(
  BSTR const strFieldName,  // in
  BSTR *strOut              // out, return value
);

Parameters

[VB][JAVA][C++] strFieldName
String specifying the name of the field to return. The currently valid strings for field names are listed here.
Field Name | Description
CommonName | Common name of the server
OrgUnit | Organizational unit
Organization | Organization
Locality | City or town
State | State or province
Country | Country
Config | Reference machine/server name
ExchangeCertificate | Certificate to send encrypted content
SignatureCertificate | Root signing certificate
Comment | Descriptive comment about the server

[C++] strOut
Points to the return value. See Return Values.

Return Values

Returns the field data for the specified field.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certcli.h.
Import Library: Use certidl.lib.


ICertConfig::Next

The Next method points the ICertConfig interface to retrieve the next available certificate server configuration in the configuration point.

[VB] Long Next(void);

[JAVA] int Next(void);

[C++] HRESULT Next(
  LONG *pIndex    // out, return value
);

Parameters

[C++] pIndex
Points to the return value. See Return Values.

Return Values

Returns a value specifying the index of the next available certificate server configuration in the configuration point. If no more configurations are available, a value of –1 is specified.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certcli.h.
Import Library: Use certidl.lib.


ICertConfig::Reset

The Reset method resets the configuration query state to point at the certificate server configuration indexed on the specified configuration point. Each individual configuration will indicate a specific certificate server. Some certificate servers may have multiple valid configurations in the configuration database.

[VB] Long Reset(
  long Index
);

[JAVA] int Reset(
  int Index
);

[C++] HRESULT Reset(
  LONG Index,    // in
  LONG *pCount   // out, return value
);

Parameters

[VB][JAVA][C++] Index
Specifies the configuration point used by the configuration query to index a certificate server configuration.
[C++] pCount
Points to the return value. See Return Values.

Return Values

Returns the number of configurations in the enterprise.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certcli.h.
Import Library: Use certidl.lib.


ICertEncodeAltName Interface

The ICertEncodeAltName interface provides methods for handling alternate names used in certificate extensions. A certificate extension can be created using an alternate name array stored in an extension handler COM object instantiated by the policy podule. Each element in the array is a structure containing a name string and a name choice string.

The following methods are provided by the ICertEncodeAltName interface.

Method | Description
Decode | Decodes an ASN encoded alternate name array and stores the resulting array of strings in the COM object.
Encode | Performs ASN encoding on an alternate name array stored in the COM object and returns the array of ASN encoded strings.
GetName | Returns the alternate name at a specified index of an alternate name array.
GetNameChoice | Returns a name choice at a specified index of an alternate name array.
GetNameCount | Returns the count of names in an alternate name array.
Reset | Resets an alternate name array to a specified number of elements and initializes the values.
SetNameEntry | Sets a name and name choice at a specified index of an alternate name array.


ICertEncodeAltName::Decode

The Decode method decodes an ASN encoded alternate name array and stores the resulting array of strings in the COM object.

[VB] void Decode(
  BSTR strBinary
);

[JAVA] void Decode(
  java.lang.String strBinary
);

[C++] HRESULT Decode(
  BSTR const strBinary  // in
);

Parameters

[VB][JAVA][C++] strBinary
Points to an ASN encoded alternate name array.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeAltName::Encode

The Encode method performs ASN encoding on an alternate name array stored in the COM object and returns the array of ASN encoded strings. The Reset method must first be used to size the array, and the SetNameEntry method must be called to set each array element.

[VB] BSTR Encode(void);

[JAVA] java.lang.String Encode(void);

[C++] HRESULT Encode(
  BSTR * pstrBinary  // out
);

Parameters

[C++] pstrBinary
Points to the return value. See Return Values.

Return Values

Returns the ASN encoded alternate name array.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeAltName::GetName

The GetName method returns the alternate name at a specified index of an alternate name array.

[VB] BSTR GetName(
  long NameIndex
);

[JAVA] java.lang.String GetName(
  int NameIndex
);

[C++] HRESULT GetName(
  LONG NameIndex,             // in
  BSTR *pstrName              // out, return value
);

Parameters

[VB][JAVA][C++] NameIndex
Specifies the index of the alternate name entry.
[C++] pstrName
Points to the return value. See Return Values.

Return Values

Returns the alternate name at the specified index. The return value is a Unicode string.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeAltName::GetNameChoice

The GetNameChoice method returns the name choice at a specified index of an alternate name array.

[VB] long GetNameChoice(
  long NameIndex
);

[JAVA] int GetNameChoice(
  int NameIndex
);

[C++] HRESULT GetNameChoice(
  LONG NameIndex,             // in
  LONG *pNameChoice           // out, return value
);

Parameters

[VB][JAVA][C++] NameIndex
Specifies the index of the alternate name entry.
[C++] pNameChoice
Points to the return value. See Return Values.

Return Values

Returns the name choice at the specified index. The name choice indicates the type of the alternate name so that it can be used correctly. It must be one of the following values.

Name Choice Specifier | Description
CERT_ALT_NAME_RFC822_NAME | The name is an e-mail address.
CERT_ALT_NAME_DNS_NAME | The name is an IA5 string specifying a DNS (Domain Name System) name in the format host.entity.domain.
CERT_ALT_NAME_URL | The name is an IA5 string specifying a URL (Universal Resource Locator) in the format service://hostname/pathname.
CERT_ALT_NAME_REGISTERED_ID | The name is a registered OID (Object Identifier).

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeAltName::GetNameCount

The GetNameCount method returns the name count in an alternate name array.

[VB] long GetNameCount(void);

[JAVA] int GetNameCount(void);

[C++] HRESULT GetNameCount(
  LONG *pNameCount            // out, return value
);

Parameters

[C++] pNameCount
Points to the return value. See Return Values.

Return Values

Returns the name count.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeAltName::Reset

The Reset method resets an alternate name array to a specified number of elements. The values of all the elements are set to 0.

[VB] void Reset(
  long NameCount
);

[JAVA] void Reset(
  int NameCount
);

[C++] HRESULT Reset(
  LONG NameCount         // in
);

Parameters

[VB][JAVA][C++] NameCount
Specifies the count of elements to be initialized.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeAltName::SetNameEntry

The SetNameEntry method sets a name at a specified index of an alternate name array.

[VB] void SetNameEntry(
  long NameIndex,
  long NameChoice,
  BSTR strName
);

[JAVA] void SetNameEntry(
  int NameIndex,
  int NameChoice,
  java.lang.String strName
);

[C++] HRESULT SetNameEntry(
  LONG NameIndex,             // in
  LONG NameChoice,            // in
  BSTR const strName          // in
);

Parameters

[VB][JAVA][C++] NameIndex
Specifies the index of the alternate name entry.
[VB][JAVA][C++] NameChoice
Specifies the name choice. The name choice indicates the type of the alternate name so that it can be used correctly. It must be one of the following values.
Name Choice Specifier | Description
CERT_ALT_NAME_RFC822_NAME | The name is an e-mail address.
CERT_ALT_NAME_DNS_NAME | The name is an IA5 string specifying a DNS (Domain Name System) name in the format host.entity.domain.
CERT_ALT_NAME_URL | The name is an IA5 string specifying a URL (Universal Resource Locator) in the format service://hostname/pathname.
CERT_ALT_NAME_REGISTERED_ID | The name is a registered OID (Object Identifier).

[VB][JAVA][C++] strName
Specifies the alternate name.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeBitString Interface

The ICertEncodeBitString interface provides methods for handling bit strings used in certificate extensions. A certificate extension can be created using a bit string stored in an extension handler COM object instantiated by the policy module. The bit string can contain an arbitrary string of binary values.

The following methods are provided by the ICertEncodeBitString interface.

Method | Description
Decode | Decodes an ASN encoded bit string and stores the resulting bit string in the COM object.
Encode | Performs ASN encoding on a bit string stored in the COM object and returns the ASN encoded bit string.
GetBitCount | Returns the number of bits in a bit string.
GetBitString | Returns the bit string.


ICertEncodeBitString::Decode

The Decode method decodes an ASN encoded bit string and stores the resulting bit string in the COM object.

[VB] void Decode(
  BSTR strBinary
);

[JAVA] void Decode(
  java.lang.String strBinary
);

[C++] HRESULT Decode(
  BSTR const strBinary  // in
);

Parameters

[VB][JAVA][C++] strBinary
Points to an ASN encoded bit string.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeBitString::Encode

The Encode method performs ASN encoding on a bit string stored in the COM object and returns the ASN encoded bit string. The bit string is first initialized and then set before being encoded.

[VB] BSTR Encode(
  long BitCount,
  BSTR strBitString
);

[JAVA] java.lang.String Encode(
  int BitCount,
  java.lang.String strBitString
);

[C++] HRESULT Encode(
  LONG BitCount,            // in
  BSTR strBitString,        // in
  BSTR *pstrBinary          // out
);

Parameters

[VB][JAVA][C++] BitCount
Specifies the size of the bit string.
[VB][JAVA][C++] strBitString
Specifies the bit string.
[C++] pstrBinary
Points to the return value. See Return Values.

Return Values

Returns the ASN encoded bit string.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeBitString::GetBitCount

The GetBitCount method returns the number of bits in a bit string.

[VB] long GetBitCount(void);

[JAVA] int GetBitCount(void);

[C++] HRESULT GetBitCount(
  LONG * pBitCount           // out, return value
);

Parameters

[C++] pBitCount
Points to the return value. See Return Values.

Return Values

Returns the number of bits.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeBitString::GetBitString

The GetBitString method returns the string of bits in a bit string.

[VB] BSTR GetBitString(void);

[JAVA] java.lang.String GetBitString(void);

[C++] HRESULT GetBitString(
  BSTR *pstrBitString   // out
);

Parameters

[C++] pstrBitString
Points to the return value. See Return Values.

Return Values

Returns the bit string.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeCRLDistInfo Interface

The ICertEncodeCRLDistInfo interface provides methods for handling CRL distribution information arrays used in certificate extensions. A certificate extension can be created using a CRL distribution information array stored in an extension handler COM object instantiated by the policy module. Each element in the array is a CRL distribution point structure that contains an array of names and name choices.

The following methods are provided by the ICertEncodeCRLDistInfo interface.

Method | Description
Decode | Decodes an ASN encoded CRL distribution information array and stores the resulting array in the COM object.
Encode | Performs ASN encoding on a CRL distribution information array stored in the COM object and returns the ASN encoded array.
GetDistPointCount | Returns the number of CRL distribution point elements in a CRL distribution information array.
GetName | Returns the name at a specified index of a CRL distribution point structure.
GetNameChoice | Returns the name choice at a specified index of a CRL distribution point structure.
GetNameCount | Returns the number of names in a CRL distribution point structure.
Reset | Resets an array of CRL distribution information structures to a specified number of structures and initializes the structure elements.
SetNameCount | Sets the name count for the specified distribution point in a CRL distribution information array.
SetNameEntry | Sets the name and name choice at a specified index of a distribution point in a CRL distribution information array.


ICertEncodeCRLDistInfo::Decode

The Decode method decodes an ASN encoded CRL distribution information array and stores the resulting array in the COM object.

[VB] void Decode(
  BSTR strBinary
);

[JAVA] void Decode(
  java.lang.String strBinary
);

[C++] HRESULT Decode(
  BSTR const strBinary  // in
);

Parameters

[VB][JAVA][C++] strBinary
Points to an ASN encoded CRL distribution information array.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeCRLDistInfo::Encode

The Encode method performs ASN encoding on a CRL distribution information array stored in the COM object and returns the ASN encoded array. The Reset method must first be used to size the array, and the SetNameCount and SetNameEntry methods must be called to set each element in each distribution point structure.

[VB] BSTR Encode(void);

[JAVA] java.lang.String Encode(void);

[C++] HRESULT Encode(
  BSTR * pstrBinary  // out
);

Parameters

[C++] pstrBinary
Points to the return value. See Return Values.

Return Values

Returns the ASN encoded CRL distribution information array.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeCRLDistInfo::GetDistPointCount

The GetDistPointCount method returns the number of CRL distribution points in a CRL distribution information array.

[VB] Long GetDistPointCount(void);

[JAVA] int GetDistPointCount(void);

[C++] HRESULT GetDistPointCount(
  LONG * pDistPointCount  // out, return value
);

Parameters

[C++] pDistPointCount
Points to the return value. See Return Values.

Return Values

Returns the number of CRL distribution points.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeCRLDistInfo::GetName

The GetName method returns the name at a specified index of a CRL distribution information point.

[VB] BSTR GetName(
  long DistPointIndex,
  long NameIndex
);

[JAVA] java.lang.String GetName(
  int DistPointIndex,
  int NameIndex
);

[C++] HRESULT GetName(
  LONG DistPointIndex,        // in
  LONG NameIndex,             // in
  BSTR *pstrName              // out, return value
);

Parameters

[VB][JAVA][C++] DistPointIndex
Specifies the index of the distribution point for which to get a name.
[VB][JAVA][C++] NameIndex
Specifies the index of the name entry to get.
[C++] pstrName
Points to the return value. See Return Values.

Return Values

Returns the name at the specified index into the specified distribution point. The return value is a Unicode string.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeCRLDistInfo::GetNameChoice

The GetNameChoice method returns the name choice at a specified index of a CRL distribution information point.

[VB] long GetNameChoice(
  long DistPointIndex,
  long NameIndex
);

[JAVA] int GetNameChoice(
  int DistPointIndex,
  int NameIndex
);

[C++] HRESULT GetNameChoice(
  LONG DistPointIndex,        // in
  LONG NameIndex,             // in
  LONG *pNameChoice           // out, return value
);

Parameters

[VB][JAVA][C++] DistPointIndex
Specifies the index of the distribution point for which to get a name choice.
[VB][JAVA][C++] NameIndex
Specifies the index of the name choice entry to get.
[C++] pNameChoice
Points to the return value. See Return Values.

Return Values

Returns the name choice at the specified index. The name choice indicates the type of the name so that it can be used correctly. The name choice must be one of the following values.

Name Choice Specifier | Description
CERT_ALT_NAME_RFC822_NAME | The name is an e-mail address.
CERT_ALT_NAME_DNS_NAME | The name is an IA5 string specifying a DNS (Domain Name System) name in the format host.entity.domain.
CERT_ALT_NAME_URL | The name is an IA5 string specifying a URL (Universal Resource Locator) in the format service://hostname/pathname.
CERT_ALT_NAME_REGISTERED_ID | The name is a registered OID (Object Identifier).

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeCRLDistInfo::GetNameCount

The GetNameCount method returns the number of names in a CRL distribution point.

[VB] long GetNameCount(
  long DistPointIndex
);

[JAVA] int GetNameCount(
  int DistPointIndex
);

[C++] HRESULT GetNameCount(
  LONG DistPointIndex,        // in
  LONG * pNameCount           // out, return value
);

Parameters

[VB][JAVA][C++] DistPointIndex
Specifies the index of the distribution point for which to get the name count.
[C++] pNameCount
Points to the return value. See Return Values.

Return Values

Returns the number of names in the CRL distribution point.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeCRLDistInfo::Reset

The Reset method resets a CRL distribution information array to a specified number of distribution point structures. The values of all the elements in the array of structures are set to 0.

[VB] void Reset(
  long DistPointCount
);

[JAVA] void Reset(
  int DistPointCount
);

[C++] HRESULT Reset(
  LONG DistPointCount         // in
);

Parameters

[VB][JAVA][C++] DistPointCount
Specifies the number of CRL distribution points in the CRL distribution information array.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeCRLDistInfo::SetNameCount

The SetNameCount method sets a name count for the specified distribution point in a CRL distribution information array.

[VB] void SetNameCount(
  long DistPointIndex,
  long NameCount
);

[JAVA] void SetNameCount(
  int DistPointIndex,
  int NameCount
);

[C++] HRESULT SetNameCount(
  LONG DistPointIndex,        // in
  LONG NameCount              // in
);

Parameters

[VB][JAVA][C++] DistPointIndex
Specifies the index of the distribution point for which to set the name count.
[VB][JAVA][C++] NameCount
Specifies the name count.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeCRLDistInfo::SetNameEntry

The SetNameEntry method sets a name at a specified index of a distribution point in a CRL distribution information array.

[VB] void SetNameEntry(
  long DistPointIndex,
  long NameIndex,
  long NameChoice,
  BSTR strName
);

[JAVA] void SetNameEntry(
  int DistPointIndex,
  int NameIndex,
  int NameChoice,
  java.lang.String strName
);

[C++] HRESULT SetNameEntry(
  LONG DistPointIndex,        // in
  LONG NameIndex,             // in
  LONG NameChoice,            // in
  BSTR const strName          // in
);

Parameters

[VB][JAVA][C++] DistPointIndex
Specifies the index of the distribution point for which to set the name.
[VB][JAVA][C++] NameIndex
Specifies the index of the name entry to set.
[VB][JAVA][C++] NameChoice
Specifies the name choice of the name being set. The name choice indicates the type of the name so that it can be used correctly. The name choice must be one of the following values.
Name Choice Specifier | Description
CERT_ALT_NAME_RFC822_NAME | The name is an e-mail address.
CERT_ALT_NAME_DNS_NAME | The name is an IA5 string specifying a DNS (Domain Name System) name in the format host.entity.domain.
CERT_ALT_NAME_URL | The name is an IA5 string specifying a URL (Universal Resource Locator) in the format service://hostname/pathname.
CERT_ALT_NAME_REGISTERED_ID | The name is a registered OID (Object Identifier).

[VB][JAVA][C++] strName
Specifies the name.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeDateArray Interface

The ICertEncodeDateArray interface provides methods for handling date arrays used in certificate extensions. A certificate extension can be created using a date array stored in an extension handler COM object instantiated by the policy module. Each element in the array is a date value.

The following methods are provided by the ICertEncodeDateArray interface.

Method | Description
Decode | Decodes an ASN encoded date array and stores the resulting array of dates in the COM object.
Encode | Performs ASN encoding on a date array stored in the COM object and returns the ASN encoded date array.
GetCount | Returns the number of date values in a date array.
GetValue | Returns the date value at a specified index of a date array.
Reset | Resets a date array to a specified number of elements and initializes the values.
SetValue | Sets a date value at a specified index of a date array.


ICertEncodeDateArray::Decode

The Decode method decodes an ASN encoded date array and stores the resulting array of dates in the COM object.

[VB] void Decode(
  BSTR strBinary
);

[JAVA] void Decode(
  java.lang.String strBinary
);

[C++] HRESULT Decode(
  BSTR const strBinary  // in
);

Parameters

[VB][JAVA][C++] strBinary
Points to an ASN encoded date array.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeDateArray::Encode

The Encode method performs ASN encoding on a date array stored in the COM object and returns the ASN encoded date array. The Reset method must first be used to size the array, and the SetValue method must be called to set each element in each distribution point structure.

[VB] BSTR Encode(void);

[JAVA] java.lang.String Encode(void);

[C++] HRESULT Encode(
  BSTR * pstrBinary  // out
);

Parameters

[C++] pstrBinary
Points to the return value. See Return Values.

Return Values

Returns the ASN encoded date array.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeDateArray::GetCount

The GetCount method returns the number of date values in a date array.

[VB] void GetCount(void);

[JAVA] void GetCount(void);

[C++] HRESULT GetCount(
  LONG *pCount     // out, return value
);

Parameters

[C++] pCount
Points to the return value. See Return Values.

Return Values

Returns the number of date values contained in the date array.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeDateArray::GetValue

The GetValue method returns the date value at a specified index of a date array.

[VB] DATE GetValue(
  long Index
);

[JAVA] double GetValue(
  int Index
);

[C++] HRESULT GetValue(
  LONG Index,            // in
  DATE * pValue          // out
);

Parameters

[VB][JAVA][C++] Index
Specifies the index into the date array from which to get the date value.
[C++] pValue
Points to the return value. See Return Values.

Return Values

Returns the date value in the date array at the specified index.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeDateArray::Reset

The Reset method resets a date array to a specified number of elements. The values of all the elements in the array are set to 0.

[VB] void Reset(
  long Count
);

[JAVA] void Reset(
  int Count
);

[C++] HRESULT Reset(
  LONG Count         // in
);

Parameters

[VB][JAVA][C++] Count
Specifies the number of elements in the date array.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeDateArray::SetValue

The SetValue method sets a date value at the specified index of a date array.

[VB] void SetValue(
  long Index,
  DATE Value
);

[JAVA] void SetValue(
  int Index,
  double Value
);

[C++] HRESULT SetValue(
  LONG Index,         // in
  DATE Value          // in
);

Parameters

[VB][JAVA][C++] Index
Specifies the index into the date array at which to set a date value.
[VB][JAVA][C++] Value
Specifies the date value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeLongArray Interface

The ICertEncodeLongArray interface provides methods for handling long arrays used in certificate extensions. A certificate extension can be created using a long array stored in an extension handler COM object instantiated by the policy module. Each element in the array is a long value.

The following methods are provided by the ICertEncodeLongArray interface.

Method | Description
Decode | Decodes an ASN encoded long array and stores the resulting array of longs in the COM object.
Encode | Performs ASN encoding on a long array stored in the COM object and returns the ASN encoded long array.
GetCount | Returns the number of long values in a long array.
GetValue | Returns the long value at a specified index of a long array.
Reset | Resets a long array to a specified number of elements.
SetValue | Sets a long value at a specified index of a long array.


ICertEncodeLongArray::Decode

The Decode method decodes an ASN encoded long array and stores the resulting array of longs in the COM object.

[VB] void Decode(
  BSTR strBinary
);

[JAVA] void Decode(
  java.lang.String strBinary
);

[C++] HRESULT Decode(
  BSTR const strBinary  // in
);

Parameters

[VB][JAVA][C++] strBinary
Points to an ASN encoded long array.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeLongArray::Encode

The Encode method performs ASN encoding on a long array stored in the COM object and returns the ASN encoded long array. The Reset method must first be used to size the array, and the SetValue method must be called to set each element in each distribution point structure.

[VB] BSTR Encode(void);

[JAVA] java.lang.String Encode(void);

[C++] HRESULT Encode(
  BSTR *pstrBinary   // out
);

Parameters

[C++] pstrBinary
Points to the return value. See Return Values.

Return Values

Returns the ASN encoded long array.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeLongArray::GetCount

The GetCount method returns the number of long values in a long array.

[VB] void GetCount(void);

[JAVA] void GetCount(void);

[C++] HRESULT GetCount(
  LONG * pCount  // out, return value
);

Parameters

[C++] pCount
Points to the return value. See Return Values.

Return Values

Returns the number of long values contained in the long array.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeLongArray::GetValue

The GetValue method returns the long value at a specified index of a long array.

[VB] long GetValue(
  long Index
);

[JAVA] int GetValue(
  int Index
);

[C++] HRESULT GetValue(
  LONG Index,            // in
  LONG *pValue           // out
);

Parameters

[VB][JAVA][C++] Index
Specifies the index into the long array from which to get the long value.
[C++] pValue
Points to the return value. See Return Values.

Return Values

Returns the long value in the long array at the specified index.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeLongArray::Reset

The Reset method resets a long array to a specified number of elements. The values of all the elements in the array are set to 0.

[VB] void Reset(
  long Count
);

[JAVA] void Reset(
  int Count
);

[C++] HRESULT Reset(
  LONG Count         // in
);

Parameters

[VB][JAVA][C++] Count
Specifies the number of elements in the long array.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeLongArray::SetValue

The SetValue method sets a long value at the specified index of a long array.

[VB] void SetValue(
  long Index,
  long Value
);

[JAVA] void SetValue(
  int Index,
  int Value
);

[C++] HRESULT SetValue(
  LONG Index,         // in
  LONG Value          // in
);

Parameters

[VB][JAVA][C++] Index
Specifies the index into the long array at which to set a long value.
[VB][JAVA][C++] Value
Specifies the long value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeSampleStructure1 Interface

The ICertEncodeSampleStructure1 interface provides methods that demonstrate how to handle a custom structure to be used in certificate extensions. A certificate extension can be created using a custom structure stored in an extension handler COM object instantiated by the policy module.

The interface methods are designed to handle the _CERT_SAMPLE_STRUCTURE1_INFO sample data structure. This data structure is defined as follows:

typedef struct _CERT_SAMPLE_STRUCTURE1_INFO
{
DWORD dwVersion;
WCHAR * pwszField1;
WCHAR * pwszField2;
LONG lField3;
CRYPT_DATA_BLOB blobField4;
FILETIME dateField5;
} CERT_SAMPLE_STRUCTURE1_INFO;

The following methods are provided by the ICertEncodeSampleStructure1 interface.

Method | Description
Decode | Decodes an ASN encoded CERT_SAMPLE_STRUCTURE1_INFO structure and stores the resulting structure in the COM object.
Encode | Performs ASN encoding on a CERT_SAMPLE_STRUCTURE1_INFO structure stored in the COM object and returns the ASN encoded structure.
GetBinaryField4 | Returns the binary value contained in the blobField4 field of the CERT_SAMPLE_STRUCTURE1_INFO structure.
GetDateField5 | Returns the date value contained in the dateField5 field of the CERT_SAMPLE_STRUCTURE1_INFO structure.
GetLongField3 | Returns the long value contained in the lField3 field of the CERT_SAMPLE_STRUCTURE1_INFO structure.
GetStringField1 | Returns the string value contained in the pwszField1 field of the CERT_SAMPLE_STRUCTURE1_INFO structure.
GetStringField2 | Returns the string value contained in the pwszField2 field of the CERT_SAMPLE_STRUCTURE1_INFO structure.


ICertEncodeSampleStructure1::Decode

The Decode method decodes an ASN encoded CERT_SAMPLE_STRUCTURE1_INFO structure and stores the resulting structure in the COM object.

[VB] void Decode(
  BSTR strBinary
);

[JAVA] void Decode(
  java.lang.String strBinary
);

[C++] HRESULT Decode(
  BSTR const strBinary  // in
);

Parameters

[VB][JAVA][C++] strBinary
Points to an ASN encoded CERT_SAMPLE_STRUCTURE1_INFO structure.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeSampleStructure1::Encode

The Encode method performs ASN encoding on a CERT_SAMPLE_STRUCTURE1_INFO structure stored in the COM object and returns the ASN encoded structure.

[VB] BSTR Encode(void);

[JAVA] java.lang.String Encode(void);

[C++] HRESULT Encode(
  BSTR * pstrBinary  // out
);

Parameters

[C++] pstrBinary
Points to the return value. See Return Values.

Return Values

Returns the ASN encoded CERT_SAMPLE_STRUCTURE1_INFO structure.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeSampleStructure1::GetBinaryField4

The GetBinaryField4 method returns the binary value contained in the blobField4 field of the CERT_SAMPLE_STRUCTURE1_INFO structure.

[VB] BSTR GetBinaryField4(void);

[JAVA] java.lang.String GetBinaryField4(void);

[C++] HRESULT GetBinaryField4(
  BSTR *pstrBinary          // out, return value
);

Parameters

[C++] pstrBinary
Points to the return value. See Return Values.

Return Values

Returns the binary string value in the blobField4 field.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeSampleStructure1::GetDateField5

The GetDateField5 method returns the date value contained in the dateField5 field of the CERT_SAMPLE_STRUCTURE1_INFO structure.

[VB] DATE GetDateField5(void);

[JAVA] double GetDateField5(void);

[C++] HRESULT GetDateField5(
  DATE * pDate       // out

);

Parameters

[C++] pDate
Points to the return value. See Return Values.

Return Values

Returns the date value in the dateField5 field.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeSampleStructure1::GetLongField3

The GetLongField3 method returns the long value contained in the lField3 field of the CERT_SAMPLE_STRUCTURE1_INFO structure.

[VB] Long GetLongField3(void);

[JAVA] int GetLongField3(void);

[C++] HRESULT GetLongField3(
  LONG *pLong         // out
);

Parameters

[C++] pLong
Points to the return value. See Return Values.

Return Values

Returns the long value in the lField3 field.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeSampleStructure1::GetStringField1

The GetStringField1 method returns the string value contained in the pwszField1 field of the CERT_SAMPLE_STRUCTURE1_INFO structure.

[VB] BSTR GetStringField1(void);

[JAVA] java.lang.String GetStringField1(void);

[C++] HRESULT GetStringField1(
  BSTR *pstrString          // out, return value
);

Parameters

[C++] pstrString
Points to the return value. See Return Values.

Return Values

Returns the string value in the pwszField1 field.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeSampleStructure1::GetStringField2

The GetStringField2 method returns the string value contained in the pwszField2 field of the CERT_SAMPLE_STRUCTURE1_INFO structure.

[VB] BSTR GetStringField2(void);

[JAVA] java.lang.String GetStringField2(void);

[C++] HRESULT GetStringField2(
  BSTR *pstrString          // out, return value
);

Parameters

[C++] pstrString
Points to the return value. See Return Values.

Return Values

Returns the string value in the pwszField2 field.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeSampleStructure2 Interface

The ICertEncodeSampleStructure2 interface provides methods that demonstrate how to handle a custom structure to be used in certificate extensions. A certificate extension can be created using a custom structure stored in an extension handler COM object instantiated by the policy module.

The interface methods are designed to handle the CERT_SAMPLE_STRUCTURE2_INFO sample data structure. This data structure is defined as follows:

typedef struct _CERT_SAMPLE_STRUCTURE2_INFO
{
DWORD dwVersion;
LONG lField1;
WCHAR * pwszField2;
FILETIME dateField3;
} CERT_SAMPLE_STRUCTURE2_INFO;

The following methods are provided by the ICertEncodeSampleStructure2 interface.

Method | Description
Decode | Decodes an ASN encoded CERT_SAMPLE_STRUCTURE2_INFO structure and stores the resulting structure in the COM object.
Encode | Performs ASN encoding on a CERT_SAMPLE_STRUCTURE2_INFO structure stored in the COM object and returns the ASN encoded structure.
GetDateField3 | Returns the date value contained in the dateField3 field of the CERT_SAMPLE_STRUCTURE2_INFO structure.
GetLongField1 | Returns the long value contained in the lField1 field of the CERT_SAMPLE_STRUCTURE2_INFO structure.
GetStringField2 | Returns the string value contained in the pwszField2 field of the CERT_SAMPLE_STRUCTURE2_INFO structure.


ICertEncodeSampleStructure2::Decode

The Decode method decodes an ASN encoded CERT_SAMPLE_STRUCTURE2_INFO structure and stores the resulting structure in the COM object.

[VB] void Decode(
  BSTR strBinary
);

[JAVA] void Decode(
  java.lang.String strBinary
);

[C++] HRESULT Decode(
  BSTR const strBinary  // in
);

Parameters

[VB][JAVA][C++] strBinary
Points to an ASN encoded CERT_SAMPLE_STRUCTURE2_INFO structure.

Return Values

This method does not return a value.


ICertEncodeSampleStructure2::Encode

The Encode method performs ASN encoding on a CERT_SAMPLE_STRUCTURE2_INFO structure stored in the COM object and returns the ASN encoded structure.

[VB] BSTR Encode(void);

[JAVA] java.lang.String Encode(void);

[C++] HRESULT Encode(
  BSTR *pstrBinary   // out
);

Parameters

[C++] pstrBinary
Points to the return value. See Return Values.

Return Values

Returns the ASN encoded CERT_SAMPLE_STRUCTURE2_INFO structure.


ICertEncodeSampleStructure2::GetDateField3

The GetDateField3 method returns the date value contained in the dateField3 field of the CERT_SAMPLE_STRUCTURE2_INFO structure.

[VB] DATE GetDateField3(void);

[JAVA] double GetDateField3(void);

[C++] HRESULT GetDateField3(
  DATE *pDate       // out

);

Parameters

[C++] pDate
Points to the return value. See Return Values.

Return Values

Returns the date value in the dateField3 field.


ICertEncodeSampleStructure2::GetLongField1

The GetLongField1 method returns the long value contained in the lField1 field of the CERT_SAMPLE_STRUCTURE2_INFO structure.

[VB] Long GetLongField1(void);

[JAVA] int GetLongField1(void);

[C++] HRESULT GetLongField1(
  LONG * pLong         // out
);

Parameters

[C++] pLong
Points to the return value. See Return Values.

Return Values

Returns the long value in the lField1 field.


ICertEncodeSampleStructure2::GetStringField2

The GetStringField2 method returns the string value contained in the pwszField2 field of the CERT_SAMPLE_STRUCTURE2_INFO structure.

[VB] BSTR GetStringField2(void);

[JAVA] java.lang.String GetStringField2(void);

[C++] HRESULT GetStringField2(
  BSTR *pstrString         // out, return value
);

Parameters

[C++] pstrString
Points to the return value. See Return Values.

Return Values

Returns the string value in the pwszField2 field.


ICertEncodeStringArray Interface

The ICertEncodeStringArray interface provides methods for handling string arrays used in certificate extensions. A certificate extension can be created using a string array stored in an extension handler COM object instantiated by the policy module. Each element in the array is a string value.

The following methods are provided by the ICertEncodeStringArray interface.

Method | Description
Decode | Decodes an ASN encoded string array and stores the resulting array of strings in the COM object.
Encode | Performs ASN encoding on a string array stored in the COM object and returns the ASN encoded string array.
GetCount | Returns the number of values in a string array.
GetStringType | Returns the type of values contained in a string array.
GetValue | Returns the value at a specified index of a string array.
Reset | Resets a string array to a specified type and number of elements, and initializes the values.
SetValue | Sets a value at a specified index of a string array.


ICertEncodeStringArray::Decode

The Decode method decodes an ASN encoded string array and stores the resulting array of strings in the COM object.

[VB] void Decode(
  BSTR strBinary
);

[JAVA] void Decode(
  java.lang.String strBinary
);

[C++] HRESULT Decode(
  BSTR const strBinary  // in
);

Parameters

[VB][JAVA][C++] strBinary
Points to an ASN encoded string array.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeStringArray::Encode

The Encode method performs ASN encoding on a string array stored in the COM object and returns the ASN encoded string array. The Reset method must first be used to size the array, and the SetValue method must be called to set each element in each distribution point structure.

[VB] BSTR Encode(void);

[JAVA] java.lang.String Encode(void);

[C++] HRESULT Encode(
  BSTR *pstrBinary  // out
);

Parameters

[C++] pstrBinary
Points to the return value. See Return Values.

Return Values

Returns the ASN encoded string array.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeStringArray::GetCount

The GetCount method returns the number of string values in a string array.

[VB] void GetCount(void);

[JAVA] void GetCount(void);

[C++] HRESULT GetCount(
  LONG *pCount  // out, return value
);

Parameters

[C++] pCount
Points to the return value. See Return Values.

Return Values

Returns the number of string values contained in the string array.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeStringArray::GetStringType

The GetStringType method returns the type of string values contained in a string array.

[VB] Long GetStringType(void);

[JAVA] int GetStringType(void);

[C++] HRESULT GetStringType(
  LONG *pStringType   // out, return value
);

Parameters

[C++] pStringType
Points to the return value. See Return Values.

Return Values

Returns a value indicating the type of string values in the string array. The string type must be one of the following types.

String Type Specifier | Description
CERT_RDN_ANY_TYPE | For encoding an X509_UNICODE_NAME name. The object identifier of the name component is used to determine the RDN type.
CERT_RDN_NUMERIC_STRING | The characters 0 through 9 and the space character (8 bit).
CERT_RDN_PRINTABLE_STRING | Printable characters (8 bit).
CERT_RDN_T61_STRING | T.61 encoded characters (8 bit).
CERT_RDN_VIDEOTEX_STRING | VIDEOTEX characters.
CERT_RDN_IA5_STRING | IA5 (ASCII) characters.
CERT_RDN_GRAPHIC_STRING | A string of ISO defined GRAPHIC characters.
CERT_RDN_ISO646_STRING | 128 character set (8 bit).
CERT_RDN_GENERAL_STRING | A string of ISO defined GENERAL characters.
CERT_RDN_INT4_STRING | An array of INT4 values (32 bit).
CERT_RDN_UNICODE_STRING | Unicode characters (16 bit).

For more information about RDN types, please refer to the CryptoAPI 2.0 documents.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeStringArray::GetValue

The GetValue method returns the string value at a specified index of a string array.

[VB] BSTR GetValue(
  long Index
);

[JAVA] java.lang.String GetValue(
  int Index
);

[C++] HRESULT GetValue(
  LONG Index,            // in
  BSTR *pstr             // out
);

Parameters

[VB][JAVA][C++] Index
Specifies the index into the string array from which to get the string value.
[C++] pstr
Points to the return value. See Return Values.

Return Values

Returns the string value in the string array at the specified index.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeStringArray::Reset

The Reset method resets a string array to a specified number and type of elements. The values of all the elements in the string array are set to 0.

[VB] void Reset(
  long Count,
  long StringType
);

[JAVA] void Reset(
  int Count,
  int StringType
);

[C++] HRESULT Reset(
  LONG Count,         // in
  LONG StringType     // in
);

Parameters

[VB][JAVA][C++] Count
Specifies the number of elements in the string array.
[VB][JAVA][C++] StringType
Specifies the type of the elements in the string array. The type must be one of the following types.
String Type Specifier | Description
CERT_RDN_ANY_TYPE | For encoding an X509_UNICODE_NAME name. The object identifier of the name component is used to determine the RDN type.
CERT_RDN_NUMERIC_STRING | The characters 0 through 9 and the space character (8 bit).
CERT_RDN_PRINTABLE_STRING | Printable characters (8 bit).
CERT_RDN_T61_STRING | T.61 encoded characters (8 bit).
CERT_RDN_VIDEOTEX_STRING | VIDEOTEX characters.
CERT_RDN_IA5_STRING | IA5 (ASCII) characters.
CERT_RDN_GRAPHIC_STRING | A string of ISO defined GRAPHIC characters.
CERT_RDN_ISO646_STRING | 128 character set (8 bit).
CERT_RDN_GENERAL_STRING | A string of ISO defined GENERAL characters.
CERT_RDN_INT4_STRING | An array of INT4 values (32 bit).
CERT_RDN_UNICODE_STRING | Unicode characters (16 bit).

For more information about RDN types, please refer to the CryptoAPI 2.0 documents.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertEncodeStringArray::SetValue

The SetValue method sets a string value at the specified index of a string array.

[VB] void SetValue(
  long Index,
  BSTR str
);

[JAVA] void SetValue(
  int Index,
  java.lang.String str
);

[C++] HRESULT SetValue(
  LONG Index,         // in
  BSTR const str      // in
);

Parameters

[VB][JAVA][C++] Index
Specifies the index into the string array at which to set a string value.
[VB][JAVA][C++] str
Specifies the string value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certenc.h.
Import Library: Use certidl.lib.


ICertExit Interface

The ICertExit interface is called by the certificate server to notify an exit module that an event of interest to the exit module has occurred. Examples of such events are certificate issuance, CRL issuance, or server shutdown. The exit module can then query the server through the ICertServerExit interface to determine the properties of any object associated with the event, such as a certificate or CRL.

The following methods are provided by the ICertExit interface.

Method | Description
GetDescription | Returns a human readable description of the exit module and its function.
Initialize | Called by the Server Engine when it initializes itself.
Notify | Called by the Server Engine to notify an exit module that an event has occurred.


ICertExit::GetDescription

The GetDescription method returns a human readable description of the exit module and its function.

[VB] BSTR GetDescription(void);

[JAVA] java.lang.String GetDescription(void);

[C++] HRESULT GetDescription(
  BSTR *strDescription    // out, return value
);

Parameters

[C++] strDescription
Points to the return value. See Return Values.

Return Values

Returns a string describing the policy module and its function.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certexit.h.
Import Library: Use certidl.lib.


ICertExit::Initialize

The Initialize method is called by the Server Engine when it initializes itself. The call to the exit module's Initialize method allows the exit module to perform initialization and inform the Server Engine which kinds of events it would like to be notified of.

[VB] Long Initialize(
  BSTR strConfig
);

[JAVA] int Initialize(
  BSTR strConfig
);

[C++] HRESULT Initialize(
  BSTR const strConfig,  // in
  LONG *pEventMask       // out, return value
);

Parameters

[VB][JAVA][C++] strConfig
Points to a valid configuration string for the certificate server. See ICertConfig::GetConfig.
[C++] pEventMask
Points to the return value. See Return Values.

Return Values

Returns a mask containing flags indicating specific events that the exit module wishes to be notified of. After the call, all events of those types will be signalled by the Server Engine to the exit module through a call to Notify. Any or all of the following flags may be set.

Name | Description
EXITEVENT_INVALID | Invalid event.
EXITEVENT_CERTISSUED | Certificate issued.
EXITEVENT_CERTPENDING | Certificate pending.
EXITEVENT_CERTDENIED | Certificate denied.
EXITEVENT_CERTREVOKED | Certificate revoked.
EXITEVENT_CERTRETRIEVEPENDING | Retrieval of pending certificate successful.
EXITEVENT_CRLISSUED | CRL issued.
EXITEVENT_SHUTDOWN | Certificate Server shutdown.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certexit.h.
Import Library: Use certidl.lib.


ICertExit::Notify

The Notify method is called by the Server Engine to notify an exit module that an event has occurred.

[VB] void Notify(
  long Event,
  long Context
);

  int Event,
  int Context
);

[C++] HRESULT Notify(
  LONG Event,     // in
  LONG Context    // in
);

Parameters

[VB][JAVA][C++] Event
A mask indicating the kind of event that has occurred. The mask can have one of the following flag-bits set.
Name | Description
EXITEVENT_INVALID | Invalid event
EXITEVENT_CERTISSUED | Certificate issued
EXITEVENT_CERTPENDING | Certificate pending
EXITEVENT_CERTDENIED | Certificate denied
EXITEVENT_CERTREVOKED | Certificate revoked
EXITEVENT_CERTRETRIEVEPENDING | Retrieval of pending certificate successful.
EXITEVENT_CRLISSUED | CRL issued
EXITEVENT_SHUTDOWN | Certificate Server shutdown

[VB][JAVA][C++] Context
Specifies a context handle that can be used to get properties associated with the event from the ICertServerExit interface.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certexit.h.
Import Library: Use certidl.lib.


ICertManageModule Interface

[This is preliminary documentation and subject to change.]

The ICertManageModule interface is provided to retrieve information about a Certificate Server Policy or Exit module. Additionally, the ICertManageModule interface provides a method to invoke the module user interface for setting and viewing configuration settings. The ICertManageModule is instantiated through a call to the COM functions CoCreateInstance or CoCreateInstanceEx.

The following methods are provided by the ICertManageModule interface.

Method | Description
Configure | Invokes module configuration user interface.
GetCopyright | Retrieves module copyright data.
GetDescription | Retrieves module description.
GetFileVersion | Retrieves module file version.
GetName | Retrieves module name.
GetProductVersion | Retrieves module product version.


ICertManageModule::Configure

[This is preliminary documentation and subject to change.]

The Configure method displays the module user interface.

[VB] Configure(
  String strConfig
);

[JAVA] Configure(
  java.lang.String strConfig
);

[C++] HRESULT Configure(
  BSTR const strConfig  // in
);

Parameters

strConfig
Value representing the Certificate Server to be configured. The text in strConfig is the name of the Certificate Server. Note that the name of the Certificate Server is identical to the common name entered during the Certificate Server setup process unless the common name contains characters which are not allowed for file names, registry keys, or registry values. In the event the common name contains any unallowable characters, strConfig is a modified name of the common name (modified to not contain any of the unallowable characters).

Return Values

[C++] The return value is an HRESULT. A value of S_OK indicates success.

Remarks

The Configure method displays the module user interface, allowing the user to view and change the module's configurable items.

Example

HRESULT             hr;
BSTR                strCertServ = NULL;
ICertManageModule * pIManageModule = NULL;

// instantiate ICertManageModule object
hr = CoCreateInstance(
          myClsid,
          NULL,
          CLSCTX_INPROC_SERVER,
          IID_ICertManageModule,
          (void **) &pIManageModule);
if ( FAILED( hr ) )
{
    printf("Unable to instantiate ICertManageModule object\n");
    goto error;
}

bstrCertServ = SysAllocString("MyCertServ");
// display the configuration interface
hr = pIManageModule->Configure( bstrCertServ );
if ( S_OK == hr )
{
    // user interface is displayed...
}
else
    printf("ICertManageModule::Configure failed with code %x\n", hr);

error:
// free resources when done
if ( NULL != bstrCertServ )
    SysFreeString( bstrCertServ );
if ( NULL != pIManageModule )
    pIManageModule->Release();

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certmod.h.
Import Library: Use certidl.lib.


ICertManageModule::GetCopyright

[This is preliminary documentation and subject to change.]

The GetCopyright method retrieves the copyright information in the module.

[VB] String GetCopyright();

[JAVA] java.lang.String GetCopyright();

[C++] HRESULT GetCopyright(
  BSTR *pstrCopyright         // out
);

Parameters

[C++] pstrCopyright
Pointer to a BSTR type that will contain the copyright information. The GetCopyright method fails if pstrCopyright is NULL. It is the caller's responsibility to call SysFreeString when done with pstrCopyright.

Return Values

[VB][JAVA] The return value is a String representing the copyright information.

[C++] The return value is an HRESULT. A value of S_OK indicates success.

Remarks

The GetCopyright method is used to retrieve the copyright information for the module.

Example

HRESULT   hr;
BSTR      bstrCopyright = NULL;

// pIManageModule is previously instantiated ICertManageModule object
hr = pIManageModule->GetCopyright( &bstrCopyright );
if ( S_OK == hr )
    printf("Copyright is: %S\n", bstrCopyright );

// free resources when done
if ( NULL != bstrCopyright )
    SysFreeString( bstrCopyright );

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certmod.h.
Import Library: Use certidl.lib.


ICertManageModule::GetDescription

[This is preliminary documentation and subject to change.]

The GetDescription method retrieves the description of the module.

[VB] String GetDescription();

[JAVA] java.lang.String GetDescription();

[C++] HRESULT GetDescription(
  BSTR *pstrDesc         // out
);

Parameters

[C++] pstrDesc
Pointer to a BSTR type that will contain the module description. The GetDescription method fails if pstrDesc is NULL. It is the caller's responsibility to call SysFreeString when done with pstrDesc.

Return Values

[VB][JAVA] The return value is a String representing the module description.

[C++] The return value is an HRESULT. A value of S_OK indicates success.

Remarks

The GetDescription method is used to retrieve the description of the module.

Example

HRESULT   hr;
BSTR      bstrDesc = NULL;

// pIManageModule is previously instantiated ICertManageModule object
hr = pIManageModule->GetDescription( &bstrDesc );
if ( S_OK == hr )
    printf("Description is: %S\n", bstrDesc );

// free resources when done
if ( NULL != bstrDesc )
    SysFreeString( bstrDesc );

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certmod.h.
Import Library: Use certidl.lib.


ICertManageModule::GetFileVersion

[This is preliminary documentation and subject to change.]

The GetFileVersion method retrieves the file version information for the module.

[VB] String GetFileVersion();

[JAVA] java.lang.String GetFileVersion();

[C++] HRESULT GetFileVersion(
  BSTR *pstrFileVersion         // out
);

Parameters

[C++] pstrFileVersion
Pointer to a BSTR type that will contain the file version. The GetFileVersion method fails if pstrFileVersion is NULL. It is the caller's responsibility to call SysFreeString when done with pstrFileVersion.

Return Values

[VB][JAVA] The return value is a String representing the file version information.

[C++] The return value is an HRESULT. A value of S_OK indicates success.

Remarks

The GetFileVersion method is used to retrieve the file version information for the module.

Example

HRESULT   hr;
BSTR      bstrFileVersion = NULL;

// pIManageModule is previously instantiated ICertManageModule object
hr = pIManageModule->GetFileVersion( &bstrFileVersion );
if ( S_OK == hr )
    printf("FileVersion is: %S\n", bstrFileVersion );

// free resources when done
if ( NULL != bstrFileVersion )
    SysFreeString( bstrFileVersion );

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certmod.h.
Import Library: Use certidl.lib.


ICertManageModule::GetName

[This is preliminary documentation and subject to change.]

The GetName method retrieves the name of the module.

[VB] String GetName();

[JAVA] java.lang.String GetName();

[C++] HRESULT GetName(
  BSTR *pstrName         // out
);

Parameters

[C++] pstrName
Pointer to a BSTR type that will contain the name of the module. The GetName method fails if pstrName is NULL. It is the caller's responsibility to call SysFreeString when done with pstrName.

Return Values

[VB][JAVA] The return value is a String representing the name of the module.

[C++] The return value is an HRESULT. A value of S_OK indicates success.

Remarks

The GetName method is used to retrieve the name of the module.

Example

HRESULT   hr;
BSTR      bstrName = NULL;

// pIManageModule is previously instantiated ICertManageModule object
hr = pIManageModule->GetName( &bstrName );
if ( S_OK == hr )
    printf("Name is: %S\n", bstrName );

// free resources when done
if ( NULL != bstrName )
    SysFreeString( bstrName );

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certmod.h.
Import Library: Use certidl.lib.


ICertManageModule::GetProductVersion

[This is preliminary documentation and subject to change.]

The GetProductionVersion method retrieves the product version.

[VB] String GetProductVersion();

[JAVA] java.lang.String GetProductVersion();

[C++] HRESULT GetProductVersion(
  BSTR *pstrProdVersion         // out
);

Parameters

[C++] pstrProdVersion
Pointer to a BSTR type that will contain the product version of the module. The GetProductVersion method fails if pstrProdVersion is NULL. It is the caller's responsibility to call SysFreeString when done with pstrProdVersion.

Return Values

[VB][JAVA] The return value is a String representing the product version.

[C++] The return value is an HRESULT. A value of S_OK indicates success.

Remarks

The GetProductVersion method is used to retrieve the product version information for the module.

Example

HRESULT   hr;
BSTR      bstrProdVersion = NULL;

// pIManageModule is previously instantiated ICertManageModule object
hr = pIManageModule->GetProductVersion( &bstrProdVersion );
if ( S_OK == hr )
    printf("ProductVersion is: %S\n", bstrProdVersion );

// free resources when done
if ( NULL != bstrProdVersion )
    SysFreeString( bstrProdVersion );

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certmod.h.
Import Library: Use certidl.lib.


ICertPolicy Interface

The ICertPolicy interface is used by the Server Engine to notify the policy module that a new certificate request has arrived for consideration. The policy module can then return to the server that the request is good and should be issued, is bad and should be denied, or should be pended for later consideration.

The pending request status will send a certificate into the certificate queue for consideration by the admin. Note that the admin may be automated to mark the request in some way and later resubmit the request to the policy module.

The following methods are provided by the ICertPolicy interface.

Method | Description
GetDescription | Returns a human readable description of the policy module and its function.
Initialize | Called by the Server Engine to allow the policy module to perform initialization tasks.
Shutdown | Called by the Server Engine before the server is terminated.
VerifyRequest | Notifies the policy module that a new request has entered the system.


ICertPolicy::GetDescription

The GetDescription method returns a human readable description of the policy module and its function.

[VB] BSTR GetDescription(void);

[JAVA] java.lang.String GetDescription(void);

[C++] HRESULT GetDescription(
  BSTR *pstrDescription    // out, return value
);

Parameters

[C++] pstrDescription
Points to the return value. See Return Values.

Return Values

Returns a string describing the policy module and its function.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certpol.h.
Import Library: Use certidl.lib.


ICertPolicy::Initialize

The Initialize method is called by the Server Engine to allow the policy module to perform initialization tasks. StrConfig will point to the currently active configuration name that the certificate server is running under.

[VB] void Initialize(
  BSTR strConfig
);

[JAVA] void Initialize(
  java.lang.String strConfig
);

[C++] HRESULT Initialize(
  BSTR const strConfig      // in
);

Parameters

[VB][JAVA][C++] strConfig
Points to a valid configuration string for the certificate server. See ICertConfig::GetConfig.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certpol.h.
Import Library: Use certidl.lib.


ICertPolicy::Shutdown

The ShutDown method is called by the Server Engine before the server is terminated. When ShutDown is called, the policy module should cleanup and stop. It is guaranteed that no requests will arrive after Shutdown is called.

[VB] void ShutDown(void);

[JAVA] void ShutDown(void);

[C++] HRESULT ShutDown(void);

Parameters

None.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certpol.h.
Import Library: Use certidl.lib.


ICertPolicy::VerifyRequest

The VerifyRequest method notifies the policy module that a new request h as entered the system. The policy module can then interact with that request by passing Context as a parameter when retrieving or setting properties on the request or associated certificate.

The return value indicates whether the request has been immediately accepted or denied, or if it is to be pended to the admin queue for later evaluation.

[VB] long VerifyRequest(
  BSTR strConfig,
  long Context,
  long bNewRequest,
  long Flags
);

[JAVA] int VerifyRequest(
  java.lang.String strConfig,
  int Context,
  int bNewRequest,
  int Flags
);

[C++] HRESULT VerifyRequest(
  BSTR const strConfig,  // in
  LONG Context,          // in
  LONG bNewRequest,      // in
  LONG Flags,            // in
  LONG *pDisposition     // out, return value
);

Parameters

[VB][JAVA][C++] strConfig
Points to a valid configuration string for the certificate server. See ICertConfig::GetConfig.
[VB][JAVA][C++] Context
Identifies the request and associated certificate under construction.
[VB][JAVA][C++] bNewRequest
Specifies that the request is a new one if set to TRUE. If set to FALSE, the request is being made to check on the status of a previous request. A value of FALSE can be used to indicate that the admin wishes the request to be issued, or that request properties set by the admin should be examined.
[VB][JAVA][C++] Flags
This parameter is undefined and must be set to 0.
[C++] pDisposition
Points to the return value. See Return Values.

Return Values

Returns a value specifying the disposition, which must be one of the following values.

VR_INSTANT_OK | The request should be issued
VR_INSTANT_BAD | The request should be denied
VR_PENDING | The request should be added to the admin queue

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certpol.h.
Import Library: Use certidl.lib.


ICertRequest Interface

The ICertRequest interface encapsulates a single certificate request to a particular certificate server. ICertRequest includes methods for submitting the request, checking the status, and retrieving the resultant certificate. In addition, the root certificate for the certificate server is available through this interface.

The following methods are provided by the ICertRequest interface.

Method | Description
GetCACertificate | Returns the root certificate for the certificate server.
GetCertificate | Returns the certificate issued for the request.
GetDispositionMessage | Gets a human-readable message for the current disposition of the certificate request.
GetLastStatus | Gets the last return code for this request.
GetRequestId | Gets the current internal request number for the request and subsequent certificate.
RetrievePending | Attempts to retrieve a certificate from a pending request.
Submit | Submits a request to the certificate server.


ICertRequest::GetCACertificate

The GetCACertificate method returns the root certificate for the certificate server.

[VB] BSTR GetCACertificate(
  long fExchangeCertificate,
  BSTR strConfig,
  long Flags
);

[JAVA] java.lang.String GetCACertificate(
  int fExchangeCertificate,
  java.lang.String strConfig,
  int Flags
);

[C++] HRESULT GetCACertificate(
  LONG fExchangeCertificate,  // in
  BSTR const strConfig,       // in
  LONG Flags,                 // in
  BSTR *strCertificate        // out, return value
);

Parameters

[VB][JAVA][C++] fExchangeCertificate
A boolean value specifying which CA certificate to return. If set to TRUE, the CA's Exchange certificate will be returned. The CA's Exchange certificate can be used to encrypt requests sent to the CA. If set to FALSE, the CA's Signature certificate will be returned. The CA's Signature certificate can be used to verify signatures on certificates issued by the CA.
[VB][JAVA][C++] strConfig
Points to a valid configuration string for the certificate server. See ICertConfig::GetConfig.
[VB][JAVA][C++] Flags
The following flags can be used to specify the format of the returned certificate.
Certificate Format Flag | Description
CR_OUT_BASE64HEADER | BASE64 format with begin/end.
CR_OUT_BASE64 | BASE64 format without begin/end.
CR_OUT_BINARY | Binary format.

The following flag can be used to specify that the complete certificate chain should be included with the requested CA certificate. Otherwise, just the requested CA certificate is returned.
Certificate Flag | Description
CR_OUT_CHAIN | Include complete certificate chain.

For example, to retrieve a binary CA certificate with complete certificate chain, in C++ you would write:

hResult = GetCACertificate(CR_OUT_BINARY | CR_OUT_CHAIN, &pstrCert);
[C++] strCertificate
Points to the return value. See Return Values.

Return Values

Returns the root certificate for the certificate server, in the specified format.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certcli.h.
Import Library: Use certidl.lib.


ICertRequest::GetCertificate

The GetCertificate method returns the certificate issued for the request, packaged in a PKCS#7 message, including the complete certificate chain for the certificate server.

[VB] BSTR GetCertificate(
  long Flags
);

[JAVA] java.lang.String GetCertificate(
  int Flags
);

[C++] HRESULT GetCertificate(
  LONG Flags,              // in
  BSTR *pstrCertificate    // out, return value
);

Parameters

[VB][JAVA][C++] Flags
One of the following flags can be used to specify the format of the returned certificate.
Certificate Format Flag | Description
CR_OUT_BASE64HEADER | BASE64 format with begin/end.
CR_OUT_BASE64 | BASE64 format without begin/end.
CR_OUT_BINARY | Binary format.

The following flag can be used to specify that the complete certificate chain should be included with the requested certificate. Otherwise, just the requested certificate is returned.
Certificate Flag | Description
CR_OUT_CHAIN | Include complete certificate chain.

For example, to retrieve a binary certificate with complete certificate chain, in C++ you would write:

hResult = GetCertificate(CR_OUT_BINARY | CR_OUT_CHAIN, &pstrCert);
[C++] pstrCertificate
Points to the return value. See Return Values.

Return Values

Returns the requested certificate.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certcli.h.
Import Library: Use certidl.lib.


ICertRequest::GetDispositionMessage

The GetDispositionMessage method gets a human-readable message for the current disposition of the certificate request. Note that the message returned here may have more detail than the returned error code. For example, GetLastStatus may return CR_DISP_DENIED, while GetDispositionMessage will return a detailed reason why the request was denied.

[VB] BSTR GetDispositionMessage(void);

[JAVA] java.lang.String GetDispositionMessage(void);

[C++] HRESULT GetDispositionMessage(
  BSTR *pstrDispositionMessage   // out, return value
);

Parameters

[C++] pstrDispositionMessage
Points to the return value. See Return Values.

Return Values

Returns a string containing a human-readable message for the current disposition of the certificate request.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certcli.h.
Import Library: Use certidl.lib.


ICertRequest::GetLastStatus

The GetLastStatus method gets the last return code for this request. This returns the error information, rather than the status of the request.

[VB] long GetLastStatus(void);

[JAVA] int GetLastStatus(void);

[C++] HRESULT GetLastStatus(
  LONG *pStatus           // out, return value
);

Parameters

[C++] pStatus
See Return Values.

Return Values

Returns a value specifying the last return code (disposition) for the request. See disposition return values listed for the ICertRequest::Submit method.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certcli.h.
Import Library: Use certidl.lib.


ICertRequest::GetRequestId

The GetRequestId method gets the current internal request number for the request and subsequent certificate. This can be used to reference a request unambiguously to a server administrator, or other interface.

[VB] Long GetRequestId(void);

[JAVA] int GetRequestId(void);

[C++] HRESULT GetRequestId(
  LONG *pRequestId    // out, return value
);

Parameters

[C++] pRequestId
Points to the return value. See Return Values.

Return Values

Returns a value specifying the current internal request number for the request and subsequent certificate.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certcli.h.
Import Library: Use certidl.lib.


ICertRequest::RetrievePending

The RetrievePending method attempts to retrieve a certificate from a request that had previously returned CR_DISP_INCOMPLETE or CR_DISP_UNDER_SUBMISSION.

[VB] Long RetrievePending(
  long RequestId,
  BSTR strConfig
);

[JAVA] int RetrievePending(
  int RequestId,
  java.lang.String strConfig
);

[C++] HRESULT RetrievePending(
  LONG RequestId,        // in
  BSTR const strConfig,  // in
  LONG *pDisposition     // out, return value
);

Parameters

[VB][JAVA][C++] RequestId
The ID of the request that had previously returned CR_DISP_INCOMPLETE or CR_DISP_UNDER_SUBMISSION.
[VB][JAVA][C++] strConfig
Points to a valid configuration string for the certificate server. See ICertConfig::GetConfig.
[C++] pDisposition
Points to the return value. See Return Values.

Return Values

Returns a value specifying the disposition of the request. The disposition can be specified by one of the following values.

Return Value | Meaning
CR_DISP_INCOMPLETE | Request did not complete
CR_DISP_ERROR | Request failed
CR_DISP_DENIED | Request denied
CR_DISP_ISSUED | Certificate issued
CR_DISP_ISSUED_OUT_OF_BAND | Certificate issued separately
CR_DISP_UNDER_SUBMISSION | Request taken under submission

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certcli.h.
Import Library: Use certidl.lib.


ICertRequest::Submit

The Submit method submits a request to the certificate server.

[VB] long Submit(
  long Flags,
  BSTR strRequest,
  BSTR strAttributes,
  BSTR  strConfig
);

[JAVA] int Submit(
  int Flags,
  java.lang.String strRequest,
  java.lang.String strAttributes,
  java.lang.String strConfig
);

[C++] HRESULT Submit(
  LONG Flags,                // in
  BSTR const strRequest,     // in
  BSTR const strAttributes,  // in
  BSTR const strConfig,      // in
  LONG *pDisposition         // out, return value
);

Parameters

[VB][JAVA][C++] Flags
Specifies the request format, type of request and whether the request is encrypted. One of the following format attribute flags can be used to specify how the request is encoded.
Format Attribute Flags | Description
CR_IN_BASE64HEADER | BASE64 format with begin/end.
CR_IN_BASE64 | BASE64 format without begin/end.
CR_IN_BINARY | Binary format.

One of the following format value flags can be used to specify the type of the request.
Format Value Flags | Description
CR_IN_PKCS10 | PKCS 10 request
CR_IN_KEYGEN | Keygen request

One of the following encryption flags can be used to specify encrypted content. (In the case of encrypted content, the server will look at content as a PKCS#7 encrypted message, encrypted to the exchange key of the server.)
Encryption Flags | Description
CR_IN_ENCRYPTED_REQUEST | Request encrypted
CR_IN_ENCRYPTED_ATTRIBUTES | Attributes encrypted

[VB][JAVA][C++] strRequest
Points to the string containing the certificate request.
[VB][JAVA][C++] strAttributes
Points to the string containing extra attributes for the request.
[VB][JAVA][C++] strConfig
Points to a valid configuration string for the certificate server. See ICertConfig::GetConfig.
[C++] pDisposition
Points to the return value. See Return Values.

Return Values

Returns a value specifying the disposition of the request. The disposition can be specified by one of the following values.

Return Value | Meaning
CR_DISP_INCOMPLETE | Request did not complete
CR_DISP_ERROR | Request failed
CR_DISP_DENIED | Request denied
CR_DISP_ISSUED | Certificate issued
CR_DISP_ISSUED_OUT_OF_BAND | Certificate issued separately
CR_DISP_UNDER_SUBMISSION | Request taken under submission

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certcli.h.
Import Library: Use certidl.lib.


ICertServerExit Interface

The ICertServerExit interface is exported by the Server Engine and is called by exit modules. ICertServerExit allows exit modules to get and enumerate elements of requests and certificates.

The following methods are provided by the ICertServerExit interface.

Method | Description
EnumerateAttributes | Returns the OID of the current attribute within the certificate to be published.
EnumerateAttributesClose | Frees any resources connected with attribute enumeration.
EnumerateAttributesSetup | Initializes the internal enumeration pointer to the first attribute within the certificate to be issued.
EnumerateExtensions | Returns the OID of the current extension within the certificate to be published.
EnumerateExtensionsClose | Frees any resources connected with extension enumeration.
EnumerateExtensionsSetup | Initializes the internal enumeration pointer to the first extension within the certificate to be issued.
GetCertificateExtension | Gets a specified certificate extension.
GetCertificateExtensionFlags | Gets the flags from the extension acquired by the most recent call to GetCertificateExtension.
GetCertificateProperty | Returns a named property from a certificate.
GetRequestAttribute | Returns a named attribute from a request.
GetRequestProperty | Returns a named property from a request.
SetContext | Sets the current instantiation of the interface to operate on the specified request.


ICertServerExit::EnumerateAttributes

The EnumerateAttributes method returns the OID of the current attribute within the certificate to be published, then increments the internal pointer to the next attribute. If the last attribute was already enumerated, the method returns NULL.

[VB] BSTR EnumerateAttributes(void);

[JAVA] java.lang.String EnumerateAttributes(void);

[C++] HRESULT EnumerateAttributes(
  BSTR *pstrAttributeName   // out, return value
);

Parameters

[C++] pstrAttributeName
Points to the return value. See Return Values.

Return Values

Returns a string specifying the name of the enumerated attribute, or NULL if the last attribute was already enumerated. Additionally, an HRESULT of S_FALSE is returned to C++ code if the last attribute was already enumerated.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certif.h.
Import Library: Use certidl.lib.


ICertServerExit::EnumerateAttributesClose

The EnumerateAttributesClose method frees any resources connected with attribute enumeration. All applications that use EnumerateAttributes should call EnumerateAttributesClose when finished enumerating.

[VB] void EnumerateAttributesClose(void);

[JAVA] void EnumerateAttributesClose(void);

[C++] HRESULT EnumerateAttributesClose(void);

Parameters

None.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certif.h.
Import Library: Use certidl.lib.


ICertServerExit::EnumerateAttributesSetup

The EnumerateAttributesSetup method initializes the internal enumeration pointer to the first attribute within the certificate to be issued.

[VB] void EnumerateAttributesSetup(
  long Flags
);

[JAVA] void EnumerateAttributesSetup(
  int Flags
);

[C++] HRESULT EnumerateAttributesSetup(
  LONG Flags  // in
);

Parameters

[VB][JAVA][C++] Flags
This parameter is undefined and must be set to 0.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certif.h.
Import Library: Use certidl.lib.


ICertServerExit::EnumerateExtensions

The EnumerateExtensions method returns the OID of the current extension within the certificate to be published, then increments the internal pointer to the next extension. If the last extension was already enumerated, the method returns NULL.

[VB] BSTR EnumerateExtensions(void);

[JAVA] java.lang.String EnumerateExtensions(void);

[C++] HRESULT EnumerateExtensions(
  BSTR *pstrExtensionName    // out, return value
);

Parameters

[C++] pstrExtensionName
Points to the return value. See Return Values.

Return Values

Returns a string specifying the name of the enumerated extension, or NULL if the last extension was already enumerated. Additionally, an HRESULT of S_FALSE is returned to C++ code if the last extension was already enumerated.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certif.h.
Import Library: Use certidl.lib.


ICertServerExit::EnumerateExtensionsClose

The EnumerateExtensionsClose method frees any resources connected with extension enumeration. All applications that use EnumerateExtensions should call EnumerateExtensionsClose when finished enumerating.

[VB] void EnumerateExtensionsClose(void);

[JAVA] void EnumerateExtensionsClose(void);

[C++] HRESULT EnumerateExtensionsClose(void);

Parameters

None.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certif.h.
Import Library: Use certidl.lib.


ICertServerExit::EnumerateExtensionsSetup

The EnumerateExtensionsSetup method initializes the internal enumeration pointer to the first extension within the certificate to be issued.

[VB] void EnumerateExtensionsSetup(
  long Flags
);

[JAVA] void EnumerateExtensionsSetup(
  int Flags
);

[C++] HRESULT EnumerateExtensionsSetup(
  LONG Flags  // in
);

Parameters

[VB][JAVA][C++] Flags
This parameter is undefined and must be set to 0.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certif.h.
Import Library: Use certidl.lib.


ICertServerExit::GetCertificateExtension

The GetCertificateExtension method gets a specified certificate extension. Note that certificate extensions are distinct from certificate properties. Properties are generic data attached to the request object. Some of these properties are encoded into the certificate (example: BeginDate), while others are just used to mark requests in the queue and log. Extensions are always encoded into the certificate, are always marked with an object ID, and always have a critical/non-critical flag.

[VB] VARIANT GetCertificateExtension(
  BSTR strExtensionName,
  long Type
);

[JAVA] com.ms.Variant GetCertificateExtension(
  java.lang.String strExtensionName,
  int Type
);

[C++] HRESULT GetCertificateExtension(
  BSTR const strExtensionName,  // in
  LONG Type,                    // in
  VARIANT *pvarValue            // out, return value
);

Parameters

[VB][JAVA][C++] strExtensionName
A string specifying the name of the extension.
[VB][JAVA][C++] Type
Specifies the type of the extension. The type can be one of the following types.
Type | Description
PROPTYPE_LONG | Signed long data
PROPTYPE_DATE | Date / Time
PROPTYPE_BINARY | Binary data
PROPTYPE_STRING | String data

[C++] pvarValue
Points to the return value. See Return Value.

Return Values

Returns the requested extension value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certif.h.
Import Library: Use certidl.lib.


ICertServerExit::GetCertificateExtensionFlags

The GetCertificateExtensionFlags method gets the flags from the extension acquired by the most recent call to GetCertificateExtension.

[VB] long GetCertificateExtensionFlags(void);

[JAVA] int GetCertificateExtensionFlags(void);

[C++] HRESULT GetCertificateExtensionFlags(
  LONG *pExtFlags   // out, return value
);

Parameters

[C++] pExtFlags
See Return Values.

Return Values

Returns a value containing the flags from the extension acquired by the most recent call to GetCertificateExtension. There are two kinds of flags used in extensions; policy flags and origin flags.

Flag Type | Explanation
Policy | Provides information about the certificate extension. Policy flags can be set by the policy module.
Origin | Indicates the module that set the certificate extension. Origin flags are only set by the Server Engine.

One or more policy flags can be returned from an extension. The following are predefined policy flags.

Policy Flag Value | Explanation
EXTENSION_CRITICAL_FLAG | This is a critical extension.
EXTENSION_DISABLE_FLAG | Extension will not be used.

One of the following origin flags can also be returned.

Origin Flag Value | Explanation
EXTENSION_ORIGIN_REQUEST | A request set the extension.
EXTENSION_ORIGIN_POLICY | Policy module set the extension.
EXTENSION_ORIGIN_ADMIN | Admin set the extension.
EXTENSION_ORIGIN_SERVER | Server Engine set the extension.

Pre-defined masks are provided for ease of use in determining which flags are set in the return value. The following masks are provided.

Mask Value | Explanation
EXTENSION_POLICY_MASK | This value (0x0000FFFF) is used to examine policy flags.
EXTENSION_ORIGIN_MASK | This value (0x000F0000) is used to examine origin flags.

Remarks

The following C++ code demonstrates use of the pre-defined mask to examine policy flags:

HRESULT hr;
LONG ExtFlags
hr = pICertServerExit->GetCertificateExtensionFlags(
    &ExtFlags);

// more than one policy flag might be set
LONG ExtPolicyFlags = ExtFlags & EXTENSION_POLICY_MASK;

if (ExtPolicyFlags & EXTENSION_CRITICAL_FLAG)
{
    // do something
}

if (ExtPolicyFlags & EXTENSION_DISABLE_FLAG)
{
    // do something
}

Note It is safe to use the high 8 bits of EXTENSION_POLICY_MASK for custom data. These bits will be saved persistently in the database, but will not be written to the certificate extensions.

The following C++ code demonstrates use of the pre-defined masks to examine origin flags:

HRESULT hr;
LONG ExtFlags
hr = pICertServerExit->GetCertificateExtensionFlags(
    &ExtFlags);

// only one origin flag can be set
switch (ExtFlags & EXTENSION_ORIGIN_MASK)
{
    case EXTENSION_ORIGIN_REQUEST:
        // extension was set in certificate request
        break;
    case EXTENSION_ORIGIN_POLICY:
        // extension was set by policy module
        break;
    case EXTENSION_ORIGIN_ADMIN:
        // extension was set by admin
        break;
    case EXTENSION_ORIGIN_SERVER:
        // extension was set by server engine
        break;
    default:
        break;
}

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certif.h.
Import Library: Use certidl.lib.


ICertServerExit::GetCertificateProperty

The GetCertificateProperty method returns a named property from a certificate.

[VB] VARIANT GetCertificateProperty(
  BSTR strPropertyName,
  long PropertyType
);

[JAVA] com.ms.Variant GetCertificateProperty(
  java.lang.String strPropertyName,
  int PropertyType
);

[C++] HRESULT GetCertificateProperty(
  BSTR const strPropertyName,  // in
  LONG PropertyType,           // in
  VARIANT *pvarPropertyValue   // out, return value
);

Parameters

[VB][JAVA][C++] strPropertyName
Specifies the named property to retrieve. There are a stock set of certificate properties that are always valid, referred to as the Name Properties. Other properties valid for certificates include the Certifcate Properties listed below.

Name Properties

These properties can refer to the subject name or the issuer name by prepending Subject or Issuer to the property. For example, Subject.OrgUnit would refer to the subject's organizational unit.

Note Only Subject name properties are supported in this release (do not prepend Issuer to a property name.)
Property Name | Data Type | Description
DistinguishedName | String | Full X.400 DN Name
RawName | Binary | ASN.1 Encoded DN
Country | String | X.500 2-character country code (for example US for United States or CA for Canada)
Organization | String | Legal name of organization
OrgUnit | String | Name of sub-organization or department
CommonName | String | Fully qualified hostname/path used in DNS (Domain Name System) lookups (for example, host.company.com)
StreetAddress | String | Street address or PO Box
Locality | String | Name of city
State | String | Full name of state or province (for example, California)
Title | String | Title of individual who requested the certificate (optional)
GivenName | String | First name of individual
Initials | String | Initials of individual (optional)
Surname | String | Last name of individual
DomainComponent | String | Component of a DNS (Domain Name System) name
E-Mail | String | E-mail address

All of the above properties except DistinguishedName, RawName, and Country support multi-valued syntax using an ANSI punctuation character as the separator, which by default must be a comma. The separator character is specified by the HKEY_LOCAL_MACHINE\SYSTEM\\CurrentControlSet\Services\CertSVC\Configuration\<CA Name>\SubjectNameSeparator (REG_SZ) entry in the system registry. This entry is set to a single character string containing a comma, by default. The first character of this string must be an ANSI punctation character to enable the multi-valued syntax. If some other character appears first, or if the registry entry is empty or missing, then multi-valued syntax is disabled.

Certificate Properties

The following properties are unique to certificates and can be read by ICertServerExit::GetCertificateProperty.
Property Name | Data Type | Description
RequestID | Signed long | Internal request ID
RawCertificate | Binary | Raw certificate bytes
SerialNumber | String | Certificate serial number
NotBefore | Date / Time | Certificate start validity date
NotAfter | Date / Time | Certificate expiration date
RawPublicKey | Binary | Subject key
PublicKeyAlgorithm | String | Subject key algorithm Object ID (OID)
RawPublicKeyAlgorithmParameters | Binary | Subject key algorithm parameters

[VB][JAVA][C++] propertyType
Specifies the property type. The type can be one of the following.
Type Specifier | Data Type
PROPTYPE_LONG | Signed long data
PROPTYPE_DATE | Date / Time
PROPTYPE_BINARY | Binary data
PROPTYPE_STRING | String data

[C++] pvarPropertyValue
Points to the return value. See Return Value.

Return Values

Returns the requested property value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certif.h.
Import Library: Use certidl.lib.


ICertServerExit::GetRequestAttribute

The GetRequestAttribute method returns a named attribute from a request.

[VB] VARIANT GetRequestAttribute(
  BSTR strAttributeName
);

[JAVA] com.ms.Variant GetRequestAttribute(
  java.lang.String strAttributeName
);

[C++] HRESULT GetRequestAttribute(
  BSTR const strAttributeName,  // in
  BSTR *pstrAttributeValue      // out, return value
);

Parameters

[VB][JAVA][C++] strAttributeName
Specifies the name of the attribute to retrieve.
[C++] pstrAttributeValue
Points to the return value. See Return Value.

Return Values

Returns the attribute value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certif.h.
Import Library: Use certidl.lib.


ICertServerExit::GetRequestProperty

The GetRequestProperty method returns a named property from a request. Note that the request is used to hold all associated states for the request and the eventual granted certificate that is not a part of the certificate. Thus, data such as revocation times and disposition data are kept in the request data object.

[VB] VARIANT GetRequestProperty(
  BSTR strPropertyName,
  long PropertyType
);

[JAVA] com.ms.Variant GetRequestProperty(
  java.lang.String strPropertyName,
  int PropertyType
);

[C++] HRESULT GetRequestProperty(
  BSTR const strPropertyName,  // in
  LONG PropertyType,           // in
  VARIANT *pvarPropertyValue   // out, return value
);

Parameters

[VB][JAVA][C++] strPropertyName
Specifies the named property to retrieve. There are a stock set of request properties that are always valid, referred to as the Name Properties. Other properties valid for certificate requests include the Request Properties and Netscape Request Properties also listed below.

Name Properties

These properties can refer to the subject name or the issuer name by prepending Subject or Issuer to the property. For example, Subject.OrgUnit would refer to the subject's organizational unit.

Note Only Subject name properties are supported in this release (do not prepend Issuer to a property name.)
Property Name | Data Type | Description
DistinguishedName | String | Full X.400 DN Name
RawName | Binary | ASN.1 Encoded DN
Country | String | X.500 2-character country code (for example US for United States or CA for Canada)
Organization | String | Legal name of the organization
OrgUnit | String | Name of sub-organization or department
CommonName | String | Fully qualified hostname/path used in DNS (Domain Name System) lookups (for example, host.company.com)
StreetAddress | String | Street address or PO Box
Locality | String | Name of city
State | String | Full name of state or province (for example, California)
Title | String | Title of individual who requested the certificate (optional)
GivenName | String | First name of individual
Initials | String | Initials of individual (optional)
Surname | String | Last name of individual
DomainComponent | String | Component of a DNS (Domain Name System) name
E-Mail | String | E-mail address

All of the above properties except DistinguishedName, RawName, and Country support multi-valued syntax using an ANSI punctuation character as the separator, which by default must be a comma. The separator character is specified by the HKEY_LOCAL_MACHINE\SYSTEM\\CurrentControlSet\Services\CertSVC\Configuration\<CA Name>\SubjectNameSeparator (REG_SZ) entry in the system registry. This entry is set to a single character string containing a comma, by default. The first character of this string must be an ANSI punctation character to enable the multi-valued syntax. If some other character appears first, or if the registry entry is empty or missing, then multi-valued syntax is disabled.

Request Properties

The following properties are unique to requests and can be accessed by ICertServerExit::GetRequestProperty.
Property Name | Data Type | Description
RequestID | Signed long | Internal requestID
RawRequest | Binary | Raw request bytes
RequestAttributes | String | Attribute string (may be truncated)
RequestType | Signed long | Indicates PKCS10 or KeyGen request
Status | Signed long | Current server status
StatusCode | Signed long | Windows error for last operation
Disposition | Signed long | Current request disposition
DispositionMessage | String | Informational disposition message
SubmittedWhen | Date / Time | When arrived
RequesterName | String | Login name of requester
ResolvedWhen | Date / Time | When resolved

The RequestType property will be one of the following values.
Format Value Flags | Description
CR_IN_PKCS10 | PKCS 10 request
CR_IN_KEYGEN | Keygen request

Netscape Request Properties

The following properties are unique to Netscape <KEYGEN> style requests.
Property Name | Type | Description
Challenge | String | Challenge returned by Navigator
ExpectedChallenge | String | Challenge issued by server

In addition, other properties may be set by a specific request type, request extensions, or by named attributes set in the header of a request.

[VB][JAVA][C++] PropertyType
Specifies the property type. The type can be one of the following types.
Type Specifier | Data Type
PROPTYPE_LONG | Signed long data
PROPTYPE_DATE | Date / Time
PROPTYPE_BINARY | Binary data
PROPTYPE_STRING | String data

[C++] pvarPropertyValue
Points to the return value. See Return Value.

Return Values

Returns the property value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certif.h.
Import Library: Use certidl.lib.


ICertServerExit::SetContext

The SetContext method causes the current instantiation of the interface to operate on the request referenced by Context. This must be identical to a value given by the Context parameter in VerifyRequest.

[VB] void SetContext(
  long Context
);

[JAVA] void SetContext(
  int   Context
);

[C++] HRESULT SetContext(
  LONG   Context  // in
);

Parameters

[VB][JAVA][C++] Context
Specifies the request and associated certificate under construction.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certif.h.
Import Library: Use certidl.lib.


ICertServerPolicy Interface

The ICertServerPolicy interface is exported by the Server Engine and is called by the policy module. It allows the policy module to get and enumerate elements of requests and certificates, to get and set certificate extensions, and to set certain certificate properties.

From the time the VerifyRequest method is called until it returns, the unresolved request and certificate under construction can be accessed through a Context data object. Because the policy module can add to or override request properties by calling SetCertificateProperty, certificate properties can differ from request properties.

The strPropertyName parameter used by all of these methods must be a property name string as described in the following section on property names.

Only those properties passed to ICertRequest as part of the named attribute string parameter or the PKCS #10 certificate request can be accessed through this method. Examples of named attributes include "RequestAttributes.Type", "RequestAttributes.Version", or other arbitrarily named properties created by a site administrator to communicate site-specific information from the request generator to the policy module. Examples of PKCS #10 property names include those beginning with the Subject, PublicKey, and Signature prefixes.

The following methods are provided by the ICertServerPolicy interface.

Method | Description
EnumerateAttributes | Returns the OID of the current attribute within the certificate to be published.
EnumerateAttributesClose | Frees any resources connected with attribute enumeration.
EnumerateAttributesSetup | Initializes the internal enumeration pointer to the first attribute within the certificate to be issued.
EnumerateExtensions | Returns the OID of the current extension within the certificate to be published.
EnumerateExtensionsClose | Frees any resources connected with extension enumeration.
EnumerateExtensionsSetup | Initializes the internal enumeration pointer to the first extension within the certificate to be issued.
GetCertificateExtension | Gets a specified certificate extension.
GetCertificateExtensionFlags | Gets the flags from the extension acquired by the most recent call to GetCertificateExtension.
GetCertificateProperty | Returns a named property from a certificate.
GetRequestAttribute | Returns a named attribute from a request.
GetRequestProperty | Returns a named property from a request.
SetCertificateExtension | Adds a new extension to the certificate to be issued.
SetCertificateProperty | Causes the Server Engine to add a named property to a certificate.
SetContext | Sets the current instantiation of the interface to operate on the specified request.


ICertServerPolicy::EnumerateAttributes

The EnumerateAttributes method returns the OID of the current attribute within the certificate to be published, then increments the internal pointer to the next attribute. If the last attribute was already enumerated, the method returns NULL.

[VB] BSTR EnumerateAttributes(void);

[JAVA] java.lang.String EnumerateAttributes(void);

[C++] HRESULT EnumerateAttributes(
  BSTR *pstrAttributeName   // out, return value
);

Parameters

[C++] pstrAttributeName
Points to the return value. See Return Values.

Return Values

Returns a string specifying the name of the enumerated attribute, or NULL if the last attribute was already enumerated. Additionally, an HRESULT of S_FALSE is returned to C++ code if the last attribute was already enumerated.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certif.h.
Import Library: Use certidl.lib.


ICertServerPolicy::EnumerateAttributesClose

The EnumerateAttributesClose method frees any resources connected with attribute enumeration. All applications that use EnumerateAttributes should call this when finished enumerating.

[VB] void EnumerateAttributesClose(void);

[JAVA] void EnumerateAttributesClose(void);

[C++] HRESULT EnumerateAttributesClose(void);

Parameters

None.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certif.h.
Import Library: Use certidl.lib.


ICertServerPolicy::EnumerateAttributesSetup

The EnumerateAttributesSetup method initializes the internal enumeration pointer to the first attribute within the certificate to be issued.

[VB] void EnumerateAttributesSetup(
  long Flags
);

[JAVA] void EnumerateAttributesSetup(
  int Flags
);

[C++] HRESULT EnumerateAttributesSetup(
  LONG Flags  // in
);

Parameters

[VB][JAVA][C++] Flags
This parameter is undefined and must be set to 0.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certif.h.
Import Library: Use certidl.lib.


ICertServerPolicy::EnumerateExtensions

The EnumerateExtensions method returns the OID of the current extension within the certificate to be published, then increments the internal pointer to the next extension. If the last extension was already enumerated, the method returns NULL.

[VB] BSTR EnumerateExtensions(void);

[JAVA] java.lang.String EnumerateExtensions(void);

[C++] HRESULT EnumerateExtensions(
  BSTR *pstrExtensionName    // out, return value
);

Parameters

[C++] pstrExtensionName
Points to the return value. See Return Values.

Return Values

Returns a string specifying the name of the enumerated extension, or NULL if the last extension was already enumerated. Additionally, an HRESULT of S_FALSE is returned to C++ code if the last extension was already enumerated.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certif.h.
Import Library: Use certidl.lib.


ICertServerPolicy::EnumerateExtensionsClose

The EnumerateExtensionsClose method frees any resources connected with extension enumeration. All applications that use EnumerateExtensions should call this when finished enumerating.

[VB] void EnumerateExtensionsClose(void);

[JAVA] void EnumerateExtensionsClose(void);

[C++] HRESULT EnumerateExtensionsClose(void);

Parameters

None.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certif.h.
Import Library: Use certidl.lib.


ICertServerPolicy::EnumerateExtensionsSetup

The EnumerateExtensionsSetup method initializes the internal enumeration pointer to the first extension within the certificate to be issued.

[VB] void EnumerateExtensionsSetup(
  long Flags
);

[JAVA] void EnumerateExtensionsSetup(
  int Flags
);

[C++] HRESULT EnumerateExtensionsSetup(
  LONG Flags  // in
);

Parameters

[VB][JAVA][C++] Flags
This parameter is undefined and must be set to 0.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certif.h.
Import Library: Use certidl.lib.


ICertServerPolicy::GetCertificateExtension

The GetCertificateExtension method gets a specified certificate extension. Note that certificate extensions are distinct from certificate properties. Properties are generic data attached to the request object. Some of these properties are encoded into the certificate (example: BeginDate), while others are just used to mark requests in the queue and log. Extensions are always encoded into the certificate, are always marked with an object ID, and always have a critical/non-critical flag.

[VB] VARIANT GetCertificateExtension(
  BSTR strExtensionName,
  long Type
);

[JAVA] com.ms.Variant GetCertificateExtension(
  java.lang.String strExtensionName,
  int Type
);

[C++] HRESULT GetCertificateExtension(
  BSTR const strExtensionName,  // in
  LONG Type,                    // in
  VARIANT *pvarValue            // out, return value
);

Parameters

[VB][JAVA][C++] strExtensionName
A string specifying the name of the extension.
[VB][JAVA][C++] Type
Specifies the type of the extension. The type can be one of the following types.
Type | Description
PROPTYPE_LONG | Signed long data
PROPTYPE_DATE | Date / Time
PROPTYPE_BINARY | Binary data
PROPTYPE_STRING | String data

[C++] pvarValue
Points to the return value. See Return Value.

Return Values

Returns the requested extension value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certif.h.
Import Library: Use certidl.lib.


ICertServerPolicy::GetCertificateExtensionFlags

The GetCertificateExtensionFlags method gets the flags from the extension acquired by the most recent call to GetCertificateExtension.

[VB] long GetCertificateExtensionFlags(void);

[JAVA] int GetCertificateExtensionFlags(void);

[C++] HRESULT GetCertificateExtensionFlags(
  LONG *pExtFlags   // out, return value
);

Parameters

[C++] pExtFlags
See Return Values.

Return Values

Returns a value containing the flags from the extension acquired by the most recent call to GetCertificateExtension. There are two kinds of flags used in extensions; policy flags and origin flags.

Flag Type | Explanation
Policy | Provides information about the certificate extension. Policy flags can be set by the policy module.
Origin | Indicates the module that set the certificate extension. Origin flags are only set by the Server Engine.

One or more policy flags can be returned from an extension. The following are predefined policy flags.

Policy Flag Value | Explanation
EXTENSION_CRITICAL_FLAG | This is a critical extension.
EXTENSION_DISABLE_FLAG | Extension will not be used.

One of the following origin flags can also be returned.

Origin Flag Value | Explanation
EXTENSION_ORIGIN_REQUEST | A request set the extension.
EXTENSION_ORIGIN_POLICY | Policy module set the extension.
EXTENSION_ORIGIN_ADMIN | Admin set the extension.
EXTENSION_ORIGIN_SERVER | Server Engine set the extension.

Pre-defined masks are provided for ease of use in determining which flags are set in the return value. The following masks are provided.

Mask Value | Explanation
EXTENSION_POLICY_MASK | This value (0x0000FFFF) is used to examine policy flags.
EXTENSION_ORIGIN_MASK | This value (0x000F0000) is used to examine origin flags.

Remarks

The following C++ code demonstrates use of the pre-defined mask to examine policy flags:

HRESULT hr;
LONG ExtFlags
hr = pICertServerExit->GetCertificateExtensionFlags(
    &ExtFlags);

// more than one policy flag might be set
LONG ExtPolicyFlags = ExtFlags & EXTENSION_POLICY_MASK;

if (ExtPolicyFlags & EXTENSION_CRITICAL_FLAG)
{
    // do something
}

if (ExtPolicyFlags & EXTENSION_DISABLE_FLAG)
{
    // do something
}

Note It is safe to use the high 8 bits of EXTENSION_POLICY_MASK for custom data. These bits will be saved persistently in the database, but will not be written to the certificate extensions.

The following C++ code demonstrates use of the pre-defined masks to examine origin flags:

HRESULT hr;
LONG ExtFlags
hr = pICertServerExit->GetCertificateExtensionFlags(
    &ExtFlags);

// only one origin flag can be set
switch (ExtFlags & EXTENSION_ORIGIN_MASK)
{
    case EXTENSION_ORIGIN_REQUEST:
        // extension was set in certificate request
        break;
    case EXTENSION_ORIGIN_POLICY:
        // extension was set by policy module
        break;
    case EXTENSION_ORIGIN_ADMIN:
        // extension was set by admin
        break;
    case EXTENSION_ORIGIN_SERVER:
        // extension was set by server engine
        break;
    default:
        break;
}

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certif.h.
Import Library: Use certidl.lib.


ICertServerPolicy::GetCertificateProperty

The GetCertificateProperty method returns a named property from a certificate.

[VB] VARIANT GetCertificateProperty(
  BSTR strPropertyName,
  long PropertyType
);

[JAVA] com.ms.Variant GetCertificateProperty(
  java.lang.String strPropertyName,
  int PropertyType
);

[C++] HRESULT GetCertificateProperty(
  BSTR const strPropertyName,  // in
  LONG PropertyType,           // in
  VARIANT *pvarPropertyValue   // out, return value
);

Parameters

[VB][JAVA][C++] strPropertyName
Specifies the named property to retrieve. There are a stock set of certificate properties that are always valid, referred to as the Name Properties. Other properties valid for certificates include the Certifcate Properties listed below.

Name Properties

These properties can refer to the subject name or the issuer name by prepending Subject or Issuer to the property. For example, Subject.OrgUnit would refer to the subject's organizational unit.

Note Only Subject name properties are supported in this release (do not prepend Issuer to a property name.)
Property Name | Data Type | Description
DistinguishedName | String | Full X.400 DN Name
RawName | Binary | ASN.1 Encoded DN
Country | String | X.500 2-character country code (for example US for United States or CA for Canada)
Organization | String | Legal name of organization
OrgUnit | String | Name of sub-organization or department
CommonName | String | Fully qualified hostname/path used in DNS (Domain Name System) lookups (for example, host.company.com)
StreetAddress | String | Street address or PO Box
Locality | String | Name of city
State | String | Full name of state or province (for example, California)
Title | String | Title of individual who requested the certificate (optional)
GivenName | String | First name of individual
Initials | String | Initials of individual (optional)
Surname | String | Last name of individual
DomainComponent | String | Component of a DNS (Domain Name System) name
E-Mail | String | E-mail address

All of the above properties except DistinguishedName, RawName, and Country support multi-valued syntax using an ANSI punctuation character as the separator, which by default must be a comma. The separator character is specified by the HKEY_LOCAL_MACHINE\SYSTEM\\CurrentControlSet\Services\CertSVC\Configuration\<CA Name>\SubjectNameSeparator (REG_SZ) entry in the system registry. This entry is set to a single character string containing a comma, by default. The first character of this string must be an ANSI punctation character to enable the multi-valued syntax. If some other character appears first, or if the registry entry is empty or missing, then multi-valued syntax is disabled.

Note The RawName property is only accessible by ICertServerPolicy::GetCertificateProperty if the certificate is requested using a non-KeyGen certificate request. For KeyGen requests, the RawName property does not exist in the certirficate until it is added after the policy module has finished processing the request and the certificate is issued. The RawName property can always be read by ICertServerExit::GetCertificateProperty.

Certificate Properties

The following properties are unique to certificates and can be read by ICertServerPolicy::GetCertificateProperty.
Property Name | Data Type | Description
RequestID | Signed long | Internal request ID
NotBefore | Date / Time | Certificate start validity date
NotAfter | Date / Time | Certificate expiration date
RawPublicKey | Binary | Subject key
PublicKeyAlgorithm | String | Subject key algorithm Object ID (OID)
RawPublicKeyAlgorithmParameters | Binary | Subject key algorithm parameters

Note There are additional certificate properties that cannot be accessed by ICertServerPolicy::GetCertificateProperty. These properties are not set until after the policy module returns VR_INSTANT_OK and the certificate is issued. See ICertServerExit::GetCertificateProperty for a complete list of all the properties in an issued certificate.

[VB][JAVA][C++] PropertyType
Specifies the property type. The type can be one of the following types.
Type Specifier | Data Type
PROPTYPE_LONG | Signed long data
PROPTYPE_DATE | Date / Time
PROPTYPE_BINARY | Binary data
PROPTYPE_STRING | String data

[C++] pvarPropertyValue
Points to the return value. See Return Value.

Return Values

Returns the requested property value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certif.h.
Import Library: Use certidl.lib.


ICertServerPolicy::GetRequestAttribute

The GetRequestAttribute method returns a named attribute from a request.

[VB] VARIANT GetRequestAttribute(
  BSTR strAttributeName
);

[JAVA] com.ms.Variant GetRequestAttribute(
  java.lang.String strAttributeName
);

[C++] HRESULT GetRequestAttribute(
  BSTR const strAttributeName,  // in
  BSTR *pstrAttributeValue      // out, return value
);

Parameters

[VB][JAVA][C++] strAttributeName
Specifies the name of the attribute to retrieve.
[C++] pstrAttributeValue
Points to the return value. See Return Value.

Return Values

Returns the attribute value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certif.h.
Import Library: Use certidl.lib.


ICertServerPolicy::GetRequestProperty

The GetRequestProperty method returns a named property from a request. Note that the request is used to hold all associated states for the request and the eventual granted certificate that is not a part of the certificate. Thus, data such as revocation times and disposition data are kept in the request data object.

[VB] VARIANT GetRequestProperty(
  BSTR strPropertyName,
  long PropertyType
);

[JAVA] com.ms.Variant GetRequestProperty(
  java.lang.String strPropertyName,
  int PropertyType
);

[C++] HRESULT GetRequestProperty(
  BSTR const strPropertyName,  // in
  LONG PropertyType,           // in
  VARIANT *pvarPropertyValue   // out, return value
);

Parameters

[VB][JAVA][C++] strPropertyName
Specifies the named property to retrieve. There are a stock set of request properties that are always valid, referred to as the Name Properties. Other properties valid for certificate requests include the Request Properties and Netscape Request Properties also listed below.

Name Properties

These properties can refer to the subject name or the issuer name by prepending Subject or Issuer to the property. For example, Subject.OrgUnit would refer to the subject's organizational unit.

Note Only Subject name properties are supported in this release (do not prepend Issuer to a property name.)
Property Name | Data Type | Description
DistinguishedName | String | Full X.400 DN Name
RawName | Binary | ASN.1 Encoded DN
Country | String | X.500 2-character country code (for example US for United States or CA for Canada)
Organization | String | Legal name of organization
OrgUnit | String | Name of sub-organization or department
CommonName | String | Fully qualified hostname/path used in DNS (Domain Name System) lookups (for example, host.company.com)
StreetAddress | String | Street address or PO Box
Locality | String | Name of city
State | String | Full name of state or province (for example, California)
Title | String | Title of individual who requested the certificate (optional)
GivenName | String | First name of individual
Initials | String | Initials of individual (optional)
Surname | String | Last name of individual
DomainComponent | String | Component of a DNS (Domain Name System) name
E-Mail | String | E-mail address

All of the above properties except DistinguishedName, RawName, and Country support multi-valued syntax using an ANSI punctuation character as the separator, which by default must be a comma. The separator character is specified by the HKEY_LOCAL_MACHINE\SYSTEM\\CurrentControlSet\Services\CertSVC\Configuration\<CA Name>\SubjectNameSeparator (REG_SZ) entry in the system registry. This entry is set to a single character string containing a comma, by default. The first character of this string must be an ANSI punctation character to enable the multi-valued syntax. If some other character appears first, or if the registry entry is empty or missing, then multi-valued syntax is disabled.

Note The RawName property does not exist in KeyGen requests, but can be read by ICertServerExit::GetRequestProperty after the policy module has finished processing the request.

Request Properties

The following properties are unique to requests and can be accessed by ICertServerPolicy::GetRequestProperty.
Property Name | Data Type | Description
RequestID | Signed long | Internal requestID
RawRequest | Binary | Raw request bytes
RequestAttributes | String | Attribute string (may be truncated)
RequestType | Signed long | Indicates PKCS10 or KeyGen request
Status | Signed long | Current server status
SubmittedWhen | Date / Time | When arrived
RequesterName | String | Login name of requester

The RequestType property can be set to one of the following values.
Format Value Flags | Description
CR_IN_PKCS10 | PKCS 10 request
CR_IN_KEYGEN | Keygen request

Note There are additional request properties that cannot be accessed by ICertServerPolicy::GetRequestProperty. These properties are not set until after the policy module finishes processing the request. See ICertServerExit::GetRequestProperty for a complete list of all the request properties.

Netscape Request Properties

The following properties are unique to Netscape <KEYGEN> style requests.
Property Name | Type | Description
Challenge | String | Challenge returned by Navigator
ExpectedChallenge | String | Challenge issued by server

In addition, other properties may be set by a specific request type, request extensions, or by named attributes set in the header of a request.

[VB][JAVA][C++] PropertyType
Specifies the property type. The type can be one of the following types.
Type Specifier | Data Type
PROPTYPE_LONG | Signed long data
PROPTYPE_DATE | Date / Time
PROPTYPE_BINARY | Binary data
PROPTYPE_STRING | String data

[C++] pvarPropertyValue
Points to the return value. See Return Value.

Return Values

Returns the requested property value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certif.h.
Import Library: Use certidl.lib.


ICertServerPolicy::SetCertificateExtension

The SetCertificateExtension method adds a new extension to the certificate to be issued.

[VB] void SetCertificateExtension(
  BSTR strExtensionName,
  long Type,
  long ExtFlags,
  VARIANT pvarValue
);

[JAVA] void SetCertificateExtension(
  java.lang.String strExtensionName,
  int Type,
  int ExtFlags,
  com.ms.Variant pvarValue
);

[C++] HRESULT SetCertificateExtension(
  BSTR const strExtensionName,  // in
  LONG Type,                 // in
  LONG ExtFlags,             // in
  VARIANT const *pvarValue   // in
);

Parameters

[VB][JAVA][C++] strExtensionName
Specifies the Object ID (OID) for the extension to set. In this release the string must be 31 or less non-null characters in length.
[VB][JAVA][C++] Type
Specifies the type of extension being set. The Type parameter must agree with the data type of pvarValue that is set in the vt field of the VARIANT structure. See Data Types. The Type parameter can be set to one of the following types.
Type | Description
PROPTYPE_LONG | Signed long data
PROPTYPE_DATE | Date / Time
PROPTYPE_BINARY | Binary data
PROPTYPE_STRING | String data

[VB][JAVA][C++] ExtFlags
Specifies the flags for the extension being set. Use a value of 0 if no flag is to be set, or one of the following flag values.
Flag Value | Explanation
EXTENSION_CRITICAL_FLAG | This is a critical extension
EXTENSION_DISABLE_FLAG | Extension will not be used

Note When ExtFlags is set to EXTENSION_DISABLE_FLAG, the extension will be disabled in the Server Log but will not be added to the certificate.

[VB][JAVA][C++] pvarValue
Specifies the value associated with the extension. Must be in decimal format or is assumed to be a string .

Return Values

This method does not return a value.

Remarks

The following C++ code sets a revocation URL string and extension critical flag into the certificate:

HRESULT hr;
BSTR strExtensionName = SysAllocString("2.29.38.4");
VARIANT varExt;
varExt.vt = VT_BSTR;    // initialize type tag field
varExt.bstrVal = SysAllocString("http://UrlTest.htm");

hr = pICertServerPolicy->SetCertificateExtension(
    strExtensionName,      // extension name
    PROPTYPE_STRING,
    EXTENSION_CRITICAL_FLAG,
    &varExt);

// Use the strAttributeValue ...

// free it when done
if (NULL != strExtensionName)
{
    SysFreeString(strExtensionName);
}
VariantClear(&varExt);

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certif.h.
Import Library: Use certidl.lib.

See Also

Setting Certificate Extensions.


ICertServerPolicy::SetCertificateProperty

The SetCertificateProperty method causes the Server Engine to add a named property to a certificate.

[VB] void SetCertificateProperty(
  BSTR strPropertyName,
  long PropertyType,
  VARIANT * pvarPropertyValue
);

[JAVA] void SetCertificateProperty(
  java.lang.String strPropertyName,
  int PropertyType,
  com.ms.Variant * pvarPropertyValue
);

[C++] HRESULT SetCertificateProperty(
  BSTR const strPropertyName,  // in
  LONG PropertyType,           // in
  VARIANT *pvarPropertyValue   // in
);

Parameters

[VB][JAVA][C++] strPropertyName
Specifies the named property to set. There are a stock set of certificate properties that are always valid, referred to as the Name Properties. Other properties valid for certificates that may be set by SetCertificateProperty include the Certifcate Properties listed below.

Name Properties

These properties can refer to the subject name or the issuer name by prepending Subject or Issuer to the property. For example, Subject.OrgUnit would refer to the subject's organizational unit. Name properties must in general be 49 or less non-null characters in length except where noted.

Note Only Subject name properties are supported in this release (do not prepend Issuer to a property name.)
Property Name | Data Type | Description
DistinguishedName | String | Full X.400 DN Name (must be 254 non-null characters or less)
Country | String | X.500 2-character country code (for example US for United States or CA for Canada)
Organization | String | Legal name of organization
OrgUnit | String | Name of sub-organization or department
CommonName | String | Fully qualified hostname/path used in DNS (Domain Name System) lookups (for example, host.company.com)
StreetAddress | String | Street address or PO Box
Locality | String | Name of city
State | String | Full name of state or province (for example, California)
Title | String | Title of individual who requested the certificate (optional)
GivenName | String | First name of individual
Initials | String | Initials of individual (optional)
Surname | String | Last name of individual
DomainComponent | String | Component of a DNS (Domain Name System) name
E-Mail | String | E-mail address

All of the above properties except DistinguishedName and Country support multi-valued syntax using an ANSI punctuation character as the separator, which by default must be a comma. The separator character is specified by the HKEY_LOCAL_MACHINE\SYSTEM\\CurrentControlSet\Services\CertSVC\Configuration\<CA Name>\SubjectNameSeparator (REG_SZ) entry in the system registry. This entry is set to a single character string containing a comma, by default. The first character of this string must be an ANSI punctation character to enable the multi-valued syntax. If some other character appears first, or if the registry entry is empty or missing, then multi-valued syntax is disabled.

Certificate Properties

The following properties are unique to certificates and can be set by ICertServerPolicy::SetCertificateProperty.
Property Name | Data Type | Description
NotBefore | Date / Time | Certificate start validity date
NotAfter | Date / Time | Certificate expiration date

Note ICertServerPolicy::SetCertificateProperty can set only the NotBefore and NotAfter certificate properties. See ICertServerExit::GetCertificateProperty for a complete list of all the properties in an issued certificate.

[VB][JAVA][C++] PropertyType
Specifies the type of the property being set. The Type parameter must agree with the data type of pvarValue that is set in the vt field of the VARIANT structure. See Data Types. The Type parameter can be set to one of the following types.
Type Specifier | Data Type
PROPTYPE_LONG | Signed long data
PROPTYPE_DATE | Date / Time
PROPTYPE_BINARY | Binary data
PROPTYPE_STRING | String data

[C++] pvarPropertyValue
Specifies the value to set the property to.

Return Values

This method does not return a value.

Remarks

The NotBefore and NotAfter certificate properties constrain the lifetime during which a certificate is valid. The data type for these properties is a VARIANT date (floating point) derived from COleDateTime in OLE Automation.

The following restrictions apply when setting the NotBefore and NotAfter certificate properties with SetCertificateProperty:

  • The NotBefore date cannot be set to a date earlier than the CA certificate's NotBefore date.
  • The NotAfter date cannot be set to a date later than the CA certificate's NotAfter date.
  • The NotBefore date cannot be set to a date earlier than it already is set, even if the new date is later than the CA certificate's NotBefore date.
  • The NotAfter date cannot be set to a date later than it already is set, even if the new date is prior to the CA certificate's NotAfter date.

The following C++ code sets the begin and expiration properties in the certificate:

hr = pICertServerPolicy->SetCertificateProperty("NotBefore",
    PROPTYPE_DATE,
    BeginDate);
hr = pICertServerPolicy->SetCertificateProperty("NotAfter",
    PROPTYPE_DATE,
    ExpireDate);

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certif.h.
Import Library: Use certidl.lib.


ICertServerPolicy::SetContext

The SetContext method causes the current instantiation of the interface to operate on the request referenced by Context. This must be identical to a value given by the Context parameter in VerifyRequest.

[VB] void SetContext(
  long Context
);

[JAVA] void SetContext(
  int Context
);

[C++] HRESULT SetContext(
  LONG Context  // in
);

Parameters

[VB][JAVA][C++] Context
Specifies the request and associated certificate under construction.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certif.h.
Import Library: Use certidl.lib.


ICertView Interface

[This is preliminary documentation and subject to change.]

The ICertView interface allows properly authorized clients to create a view of the Certificate Server database. ICertView allows the client to retrieve a customized view of the database or to retrieve the database in its entirety. ICertView is instantiated through a call to the COM function CoCreateInstance.

The following methods are provided by the ICertView interface.

Method | Description
EnumCertViewColumn | Obtains a pointer to the IEnumCERTVIEWCOLUMN interface.
GetColumnCount | Retrieves the count of columns in the view.
GetColumnIndex | Retrieves the zero-based index of a column.
OpenConnection | Establishes a connection with a Certificate Server.
OpenView | Opens a view to a Certificate Server database and obtains a pointer to the IEnumCERTVIEWROW interface.
SetRestriction | Sets sorting and qualifying restrictions on a column.
SetResultColumn | Specifies a column for use in a customized view.
SetResultColumnCount | Sets the number of columns in a customized view.


ICertView::EnumCertViewColumn

[This is preliminary documentation and subject to change.]

The EnumCertViewColumn method obtains a pointer to the IEnumCERTVIEWCOLUMN interface.

[VB] CEnumCERTVIEWCOLUMN EnumCertViewColumn(
  Boolean fResultColumn
);

[JAVA] CEnumCERTVIEWCOLUMN EnumCertViewColumn(
  java.lang.Boolean fResultColumn
);

[C++] HRESULT EnumCertViewColumn(
  BOOL fResultColumn,           // in
  IEnumCERTVIEWCOLUMN **ppenum  // out
);

Parameters

fResultColumn
If this value is TRUE, the view is based on a result set; a value of FALSE means the view is based on the full database schema. A result set is used for customizing the view of the Certificate Server data.
[C++]ppenum
Pointer to a pointer of IEnumCERTVIEWCOLUMN type. This function will fail if ppenum is NULL.

Return Values

[VB][JAVA] The return value is an IEnumCERTVIEWCOLUMN object.

[C++] The return value is an HRESULT. A value of S_OK indicates success. Upon successful completion of this function, ppenum will point to a pointer of IEnumCERTVIEWCOLUMN type.

Remarks

The IEnumCERTVIEWCOLUMN object can be used to enumerate the view's columns and retrieve each column's information.

Example

// pCertView is previously instantiated pointer to ICertView
IEnumCERTVIEWCOLUMN *    pEnumCertViewCol = NULL;
HRESULT                  hr;
hr = pCertView->EnumCertViewColumn( TRUE, &pEnumCertViewCol );
if ( S_OK != hr )
    printf("Failed EnumCERTVIEWCOLUMN call!\n");
    // call error handler…
else
    // use pEnumCertViewCol to access IEnumCERTVIEWCOL methods
// done using object; free resources
if ( NULL != pEnumCertViewCol )
    pEnumCertViewCol->Release();

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certview.h.
Import Library: Use certidl.lib.

See Also

IEnumCERTVIEWCOLUMN Interface


ICertView::GetColumnCount

[This is preliminary documentation and subject to change.]

The GetColumnCount method retrieves the count of columns in the view of the Certificate Server database.

[VB] Long GetColumnCount(
  Long fResultColumn
);

[JAVA] int GetColumnCount(
  int fResultColumn
);

[C++] HRESULT GetColumnCount(
  LONG ResultColumn,  // in
  LONG *pcColumn      // out
);

Parameters

fResultColumn
Boolean value. If this value is TRUE, the view is based on a result set; a value of FALSE means the view is based on the full database schema. A result set is used for customizing the view to the Certificate Server data.
[C++] pcColumn
Pointer to variable that will contain the number of columns in the view. This function will fail if pcColumn is NULL.

Return Values

[VB][JAVA] The return value is the number of columns in the view.

[C++] The return value is an HRESULT. A value of S_OK indicates success. Upon successful completion of this function, pcColumn will point to the variable containing the number of columns in the view.

Remarks

This function is used to determine the number of columns in the view. The number will represent the count of a result set's columns if fResultColumn is TRUE or the count of the full database schema's columns if fResultColumn is FALSE.

Example

// pCertView is pointer to ICertView
LONG        cCol
HRESULT    hr;
hr = pCertView->GetColumnCount( TRUE, &cCol );
if ( S_OK != hr )
    printf("Failed GetColumnCount - %x\n", hr);
else
    printf("Number of columns in the view is: %d\n", cCol);

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certview.h.
Import Library: Use certidl.lib.

See Also

ICertView::SetResultColumnCount


ICertView::GetColumnIndex

[This is preliminary documentation and subject to change.]

The GetColumnIndex method retrieves the zero-based index of a column.

[VB] Long GetColumnIndex(
  Long fResultColumn,
  String strColumnName
);

[JAVA] int GetColumnIndex(
  int fResultColumn,
  java.lang.String strColumnName
);

[C++] HRESULT GetColumnIndex(
  LONG fResultColumn,        // in
  BSTR const strColumnName,  // in
  LONG *pColumnIndex         // out
);

Parameters

fResultColumn
If this value is TRUE, the view is based on a result set; a value of FALSE means the view is based on the full database schema.
strColumnName
Value representing the nonlocalized name of a column in the view.
[C++] pColumnIndex
Address of variable that will contain the index of the column specified in strColumnName. This function will fail if pColumnIndex is NULL.

Return Values

[VB][JAVA] The return value is the zero-based index of the column.

[C++] The return value is an HRESULT. A value of S_OK indicates success.

Remarks

This function is used to determine the index of the view column specified by strColumnName. The column indices are zero-based (the first column is index 0).

Example

// pCertView is pointer to ICertView
LONG        index:
BSTR        bstrCol = NULL;
HRESULT     hr;
bstrCol = SysAllocString(TEXT("RequestID"));
hr = pView->GetColumnIndex( FALSE, bstrCol, &nIndex );
if ( FAILED( hr ) )
{
    printf("Failed GetColumnIndex - %x\n", hr );
    goto error;
}
printf( "Column %S has index %d\n", bstrCol, nIndex );

// free resource
if ( NULL != bstrCol )
    SysFreeString( bstrCol );

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certview.h.
Import Library: Use certidl.lib.

See Also

ICertView::SetRestriction


ICertView::OpenConnection

[This is preliminary documentation and subject to change.]

The OpenConnection method establishes a connection with a Certificate Server.

[VB] OpenConnection(
  String strConfig
);

[JAVA] OpenConnection(
  java.lang.String strConfig
);

[C++] HRESULT OpenConnection(
  BSTR const strConfig  // in
);

Parameters

strConfig
Value representing the Certificate Server that is being opened by the ICertView interface. The text in strConfig is of the form machine_name\common_name.

Return Values

[C++]The return value is an HRESULT. A value of S_OK indicates success.

Remarks

Upon successful completion of this function, the ICertView object will have a connection to the Certificate Server referenced by strConfig.

[C++] To close the connection, call ICertView::Release.

Example

ICertView *   pCertView = NULL;
BSTR          strCertServ = NULL;
HRESULT       hr;

// initialize COM
hr = CoInitializeEx( NULL, COINIT_APARTMENTTHREADED );

if ( FAILED( hr ) )
{
    printf("Failed CoInitializeEx\n");
    goto error;
}
// get pointer to the ICertView interface
hr = CoCreateInstance( CLSID_CCertView,
                       NULL,
                       CLSCTX_INPROC_SERVER,
                       IID_ICertView,
                       (void **)&pCertView);
if ( FAILED( hr ) )
{
    printf("Failed CoCreateInstance\n");
    goto error;
}
// the use of '\\' is necessary to represent a single backslash
strCertServ = SysAllocString(TEXT("Server01\\ABCCertServ"));
// open the connection to the certificate server
hr = pCertView->OpenConnection( strCertServ );
if ( FAILED( hr ) )
{
    printf("Failed OpenConnection!\n");
    goto error;
}else
    // established successful connection; use view as appropriate
    …
// done using objects; free resources
error:
if ( NULL != pCertView )
    pCertView->Release();
if ( NULL != strCertServ )
    SysFreeString( strCertServ );
// free COM resources
CoUninitialize();

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certview.h.
Import Library: Use certidl.lib.

See Also

ICertView::OpenView


ICertView::OpenView

[This is preliminary documentation and subject to change.]

The OpenView method opens a view to a Certificate Server database and obtains a pointer to the IEnumCERTVIEWROW interface.

[VB] CEnumCERTVIEWROW OpenView();

[JAVA] CEnumCERTVIEWROW OpenView();

[C++] HRESULT OpenView(
  IEnumCERTVIEWROW **ppenum  // out
);

Parameters

[C++] ppenum
Pointer to a pointer of IEnumCERTVIEWROW type.

Return Values

[VB][JAVA] The return value is a IEnumCERTVIEWROW object.

[C++] The return value is an HRESULT. A value of S_OK indicates success.

Remarks

The IEnumCERTVIEWROW object is used to enumerate the data rows in the view. The IEnumCERTVIEWROW object will be positioned to the beginning of the Certificate Server view's rows, so that a call to the object's Next method will reference the first row.

Before the ICertView OpenView method is called, it is necessary to call the ICertView OpenConnection method.

Example

// pCertView is previously instantiated pointer to ICertView
IEnumCERTVIEWROW * pEnumRow = NULL;
HRESULT    hr;

hr = pCertView->OpenView( &pEnumRow );
if ( S_OK != hr )
    printf("Failed ICertView::OpenView - %x\n", hr);
else
    // use pEnumRow as needed, to enumerate data rows
    …
// done processing, free resources
if ( NULL != pEnumRow )
    pEnumRow->Release();

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certview.h.
Import Library: Use certidl.lib.

See Also

IEnumCERTVIEWROW Interface, ICertView::OpenConnection


ICertView::SetRestriction

[This is preliminary documentation and subject to change.]

The SetRestriction method sets sorting and qualifying restrictions on a column.

[VB] SetRestriction(
  Long ColumnIndex,
  Long SeekOperator,
  Long SortOrder,
  Variant pvarValue
);

[JAVA] SetRestriction(
  int ColumnIndex,
  int SeekOperator,
  int SortOrder,
  Variant pvarValue
);

[C++] HRESULT SetRestriction(
  LONG ColumnIndex,          // in
  LONG SeekOperator,         // in
  LONG SortOrder,            // in
  VARIANT const *pvarValue   // in
);

Parameters

ColumnIndex
Must be a valid column index number for the view or a predefined column specifier. If ColumnIndex is not negative, this value represents the zero-based index of the column that is receiving the restriction.

If ColumnIndex is negative, it must be one of the values listed in the following table.
Value for ColumnIndex | Action
CV_COLUMN_LOG_DEFAULT | Restricts view to requests that have been resolved. A request is resolved if it has resulted in an issued certificate or a failed request; revoked certificates are considered resolved.
CV_COLUMN_LOG_FAILED_DEFAULT | Restricts view to requests that have failed.
CV_COLUMN_QUEUE_DEFAULT | Restricts view to requests that have not been resolved; if a request has resulted in either an issued certificate or a failed request, it will not be part of the view.

SeekOperator
This value is used with pvarValue and is used to define the data-query qualifier for the column. This value must be one of the values listed in the following table.
Value | Meaning
CVR_SEEK_EQ | Equal to
CVR_SEEK_LE | Less than or equal to
CVR_SEEK_LT | Less than
CVR_SEEK_GE | Greater than or equal to
CVR_SEEK_GT | Greater than

SortOrder
Specifies the sort order for this column, as defined in the following table.
Value | Meaning
CVR_SORT_ASCEND | Ascending
CVR_SORT_DESCEND | Descending
CVR_SORT_NONE | No sort order

pvarValue
Variant for the data query qualifier applied to this column. This value, along with the value of SeekOperator, determines which data is returned to the Certificate Server view.

Return Values

[C++] The return value is an HRESULT. A value of S_OK indicates success.

Remarks

The ICertView object maintains an array of restrictions, allowing multiple columns to contain restrictions. A column can contain more than one restriction. After the column restrictions are established, a call to the ICertView OpenView method will retrieve the data, with each column's restrictions used as part of the database query.

Before the ICertView SetRestriction method is called, it is necessary to call the ICertView OpenConnection method.

Example

// this example restricts the data,
// to rows that have RequestIDs greater than 5
// pCertView is pointer to ICertView
HRESULT    hr;
VARIANT    varRest;
LONG       nIndex;
BSTR       bstrCol = NULL;

// use one column in the result set
hr = pCertView->SetResultColumnCount( 1 );
if ( FAILED( hr ) )
{
    printf("Failed SetResultColumnCount - %x\n", hr );
    goto error;
}
// determine the column index for RequestID column
bstrCol = SysAllocString(TEXT("RequestID"));
hr = pCertView->GetColumnIndex( FALSE, bstrCol, &nIndex );
if ( FAILED( hr ) )
{
    printf("Failed GetColumnIndex - %x\n", hr );
    goto error;
}
// place this column into the result set
pCertView->SetResultColumn( nIndex );
// set a restriction on this index
VariantInit( &varRest);
varRest.vt = VT_I4;
varRest.lVal = 5;
// restrict view to requests with ID greater than 5
hr = pCertView->SetRestriction(nIndex,
                               CVR_SEEK_GT,
                               CVR_SORT_NONE,
                               &varRest);
if ( S_OK != hr )
    printf("Failed ICertView::SetRestriction - %x\n", hr);
else
    // Call OpenView, process rows, release resources, etc.
    // …
error:
// done processing, clear resources
VariantClear( &varRest );
if ( NULL != bstrCol )
    SysFreeString( bstrCol );

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certview.h.
Import Library: Use certidl.lib.

See Also

IEnumCertViewColumn::IsIndexed, ICertView::SetResultColumn


ICertView::SetResultColumn

[This is preliminary documentation and subject to change.]

The SetResultColumn method specifies a column for use in a customized view of the Certificate Server database.

[VB] SetResultColumn(
  Long iCol
);

[JAVA] SetResultColumn(
  int iCol
);

[C++] HRESULT SetResultColumn(
  LONG iCol   // in
);

Parameters

iCol
Zero-based index of a column to include in the view's result set. Prior to calling the ICertView SetResultColumn method, it is necessary to call the ICertView SetResultColumnCount method in order to specify the number of columns in the result set.

Return Values

[C++] The return value is an HRESULT. A value of S_OK indicates success.

Remarks

Upon successful completion of this function, the column specified by iCol will be included in the view's result set.

The ICertView SetResultColumnCount method must be called prior to calling SetResultColumn. After the caller has specified which columns are included in the result set via calls to SetResultColumn, the ICertView OpenView method can be called to retrieve a row enumerator for the result set. (Optionally, before calling OpenView, the caller can specify sorting/qualifying criteria through calls to the ICertView SetRestriction method.)

This function will fail if the ICertView SetResultColumnCount method has been called with a parameter value of CV_COLUMN_LOG_DEFAULT or CV_COLUMN_QUEUE_DEFAULT. This function will fail if the caller attempts to include more columns in the result set than has been specified in the call to the ICertView SetResultColumnCount method.

Example

// pCertView is pointer to ICertView
HRESULT    hr;
LONG       nIndex;
LONG       i;

// determine number of columns in the entire database
hr = pCertView->GetColumnCount( FALSE, &nIndex );
if (FAILED( hr ) )
{
    printf("Failed GetColumnCount - %x\n", hr);
    goto error;
}
hr = pCertView->SetResultColumnCount( nIndex );
if (FAILED( hr ) )
{
    printf("Failed SetResultColumnCount - %x\n", hr);
    goto error;
}
// place each column in the view
for ( i = 0; i < nIndex; i++)
{
    hr = pCertView->SetResultColumn(i);
    if ( FAILED(hr ) )
    {
        printf("Failed SetResultColumn (%d) - %x\n", i, hr );
        goto error;
    }
}
// call ICertView::OpenView, etc
// ...

error:
// clean up resources, etc

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certview.h.
Import Library: Use certidl.lib.

See Also

ICertView::SetResultColumnCount


ICertView::SetResultColumnCount

[This is preliminary documentation and subject to change.]

The SetResultColumnCount method sets the number of columns in a customized view of the Certificate Server database.

[VB] SetResultColumnCount(
  Long cCol
);

[JAVA] SetResultColumnCount(
  int cCol
);

[C++]HRESULT SetResultColumnCount(
  LONG cCol   // in
);

Parameters

cCol
Value representing how many columns will be in the view's result set. This value must not be negative, with the following exceptions:
  • cCol is CV_COLUMN_LOG_DEFAULT. In this case the number of columns in the result set will be the number of columns in the Certificate Server's default result set for requests that have been resolved. A request is resolved if it has resulted in an issued certificate or a failed request; revoked certificates are considered resolved.
  • cCol is CV_COLUMN_LOG_FAILED_DEFAULT. In this case the number of columns in the result set will be the number of columns in the Certificate Server's default result set for requests that have failed.
  • cCol is CV_COLUMN_QUEUE_DEFAULT. In this case the number of columns in the result set will be the number of columns in the Certificate Server's default result set for requests that have not been resolved.

This function will fail for any other negative values for cCol. If cCol is not negative, the ICertView SetResultColumn method must be called to specify the columns to include in the view's result set.

Return Values

[C++] The return value is an HRESULT. A value of S_OK indicates success.

Remarks

Upon successful completion of this function, the number of columns in the view's result set will be cCol if cCol is positive. If cCol is a valid negative number, the number of columns in the view's result set will correspond to a predefined result set (see the Parameters section for cCol).

The ICertView OpenConnection method must be called prior to calling SetResultColumnCount. This function will fail if called more than once on an open connection

Example

// pCertView is pointer to ICertView (which has an Open Connection)
HRESULT    hr;
// specify the result set for logged requests
hr = pCertView->SetResultColumnCount( CV_COLUMN_LOG_DEFAULT );
if ( S_OK != hr )
    printf("Failed ICertView::SetResultColumnCount - %x\n", hr);
else
    // retrieve data rows via ICertView::OpenView
    …

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certview.h.
Import Library: Use certidl.lib.

See Also

ICertView::SetResultColumn, ICertView::SetRestriction


Using the ICertView Interface

[This is preliminary documentation and subject to change.]

The ICertView interface is used by properly authorized clients to view the Certificate Server database.

A properly authorized client is a user who is a member of the Certificate Server Administrators group. Additionally, to use the ICertView object, the client workstation is required to have installed the Certificate Server client components.

Although there are various scenarios for using ICertView and its related interfaces, the following depicts one possible sequence for developing a client application based on ICertView.

  1. After obtaining an instance of the ICertView object, call OpenConnection to communicate with a Certificate Authority on a specific computer.
  2. Call SetResultColumnCount to specify the number of columns in the view; SetResultColumnCount can also be used to specify a default view. If a default view is not specified in the call to SetResultColumnCount, the caller must call SetResultColumn for each of the columns to be contained in the view.
  3. Optional. Specify sorting criteria and/or qualifying critieria for the database query by calling the SetRestriction function. Qualifying criteria consists of informing the view to retrieve data based on qualifiers such as Greater Than, Less Than, Equal To, and so on.
  4. Call OpenView to retrieve the data in the view; the view's data will consist of the columns requested via the use of SetResultColumnCount (and if a default view wasn't specified, SetResultColumn). If SetRestriction was called, data in the columns will be sorted and/or qualified. OpenView creates a IEnumCERTVIEWROW object, which can be used to enumerate the view's rows.
  5. Use the IEnumCERTVIEWROW methods EnumCertViewAttribute, EnumCertViewColumn, and EnumCertViewExtension to retrieve attribute, column, and extension data as desired.


IEnumCERTVIEWATTRIBUTE Interface

[This is preliminary documentation and subject to change.]

The IEnumCERTVIEWATTRIBUTE interface is used to access the certificate attributes for a row in the Certificate Server's view. An IEnumCERTVIEWATTRIBUTE interface is instantiated through a call to IEnumCERTVIEWROW::EnumCertViewAttribute.

The following methods are provided by the IEnumCERTVIEWATTRIBUTE interface.

Method | Description
Clone | Creates a copy of the IEnumCERTVIEWATTRIBUTE object.
GetName | Retrieves the name of the attribute.
GetValue | Retrieves the attribute value.
Next | Positions the IEnumCERTVIEWATTRIBUTE object to the next attribute.
Reset | Resets the IEnumCERTVIEWATTRIBUTE enumeration sequence to the beginning.
Skip | Skips a specified number of attributes in theIEnumCERTVIEWATTRIBUTE enumeration sequence.


IEnumCERTVIEWATTRIBUTE::Clone

[This is preliminary documentation and subject to change.]

The Clone method creates a copy of the IEnumCERTVIEWATTRIBUTE object in its current state.

[VB] CEnumCERTVIEWATTRIBUTE Clone();

[JAVA] CEnumCERTVIEWATTRIBUTE Clone();

[C++] HRESULT Clone(
  IEnumCERTVIEWATTRIBUTE **ppenum  // out
);

Parameters

[VB][JAVA] The return value is a cloned IEnumCERTVIEWATTRIBUTE object.

[C++] ppenum
Points to a pointer of IEnumCERTVIEWATTRIBUTE type. This function will fail if ppenum is NULL.

Return Values

[VB][JAVA] The return value is a cloned IEnumCERTVIEWATTRIBUTE object.

[C++] The return value is an HRESULT. A value of S_OK indicates success.

Remarks

This function is used to clone the IEnumCERTVIEWATTRIBUTE object.

Example

// pEnumAttr is previously instantied IEnumCERTVIEWATTRIBUTE object
IEnumCERTVIEWATTRIBUTE *    pEnumAttr2 = NULL;
HRESULT    hr;
hr = pEnumAttr->Clone( &pEnumAttr2 );
if ( S_OK != hr )
    printf("Unable to clone IEnumCERTVIEWATTRIBUTE\n");
else
    // use cloned object as needed
    ///…
// done using cloned object, free memory
if ( NULL != pEnumAttr2 )
    pEnumAttr2->Release();

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certview.h.
Import Library: Use certidl.lib.


IEnumCERTVIEWATTRIBUTE::GetName

[This is preliminary documentation and subject to change.]

The GetName method retrieves the name of the attribute.

[VB] String GetName();

[JAVA] Java.lang.String GetName();

[C++] HRESULT GetName(
  BSTR *pstrOutName  // out
);

Parameters

[C++] pstrOutName
Pointer to a variable of BSTR type that will contain the name of the attribute. This function will fail if pstrOutName is NULL.. It is the caller's responsibility to call SysFreeString when done with pstrOutName.

Return Values

[VB][JAVA] The return value is a String representing the name of the attribute.

[C++] The return value is an HRESULT. A value of S_OK indicates success.

Remarks

This function is used to retrieve the name of the attribute currently referenced by the IEnumCERTVIEWATTRIBUTE object.

If the IEnumCERTVIEWATTRIBUTE object is not referencing a valid attribute, GetName will fail. Use the IEnumCERTVIEWATTRIBUTE Next method to reference a valid attribute.

Example

BSTR    bstrAttribName = NULL;

// pEnumAttr is previously instantiated IEnumCERTVIEWATTRIBUTE object
hr = pEnumAttr->GetName(&bstrAttribName);
if ( S_OK != hr )
    printf("Failed call to GetName - %x\n", hr);
else
    printf("Attribute name is %S\n", bstrAttribName );

// free memory when done
if ( NULL != bstrAttribName )
    SysFreeString( bstrAttribName );

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certview.h.
Import Library: Use certidl.lib.

See Also

IEnumCERTVIEWATTRIBUTE::GetValue


IEnumCERTVIEWATTRIBUTE::GetValue

[This is preliminary documentation and subject to change.]

The GetValue method retrieves the attribute value.

[VB] String GetValue();

[JAVA] java.lang.String GetValue();

[C++] HRESULT GetValue(
  BSTR *pstrOutValue  // out
);

Parameters

[C++] pstrOutValue
Pointer to a BSTR type that will contain the value of the attribute. This function will fail if pstrOutValue is NULL. It is the caller's responsibility to call SysFreeString when done with pstrOutValue.

Return Values

[VB][JAVA] The return value is a String representing the value of the attribute.

[C++] The return value is an HRESULT. A value of S_OK indicates success.

Remarks

This function is used to retrieve the data in the attribute currently being referenced by the IEnumCERTVIEWATTRIBUTE object.

If the IEnumCERTVIEWATTRIBUTE object is not referencing a valid attribute, GetValue will fail. Use IEnumCERTVIEWATTRIBUTE::Next to reference a valid attribute.

Example

BSTR    bstrAttribValue = NULL;

// pEnumAttr is previously instantiated IEnumCERTVIEWATTRIBUTE object
hr = pEnumAttr->GetValue(&bstrAttribValue);
if ( S_OK != hr )
    printf("Failed call to GetValue - %x\n", hr);
else
    printf("Attribute value is %S\n",bstrAttribValue );

// free memory when done
if ( NULL != bstrAttribValue )
    SysFreeString( bstrAttribValue );

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certview.h.
Import Library: Use certidl.lib.

See Also

IEnumCERTVIEWATTRIBUTE::GetName


IEnumCERTVIEWATTRIBUTE::Next

[This is preliminary documentation and subject to change.]

The Next method positions the IEnumCERTVIEWATTRIBUTE object to the next attribute.

[VB] Long Next();

[JAVA] int Next();

[C++] HRESULT Next(
  LONG *pIndex  // out
);

Parameters

[C++] pIndex
Pointer to variable that will contain the index value of the next attribute being referenced. If there are no more attributes to enumerate, this variable will be set to – 1. This function will fail if pIndex is NULL.

Return Values

[VB][JAVA] The return value is the index value of the next attribute that will be referenced by the IEnumCERTVIEWATTRIBUTE object. If there are no more attributes to enumerate, the return value will be – 1.

[C++] The return value is an HRESULT. A value of S_OK indicates success and that the next attribute is now being referenced by the IEnumCERTVIEWATTRIBUTE object. If there are no more attributes, S_FALSE is returned, and pIndex will point to a value of – 1.

Remarks

Upon successful completion of this function, the IEnumCERTVIEWATTRIBUTE object will reference the next attribute. When the attribute is referenced, the attribute name and value can be accessed through the IEnumCERTVIEWATTRIBUTE methods GetName and GetValue.

Example

LONG                        Index;
HRESULT                     hr;
BSTR                        bstrAttribName = NULL;

// pEnumAttr is previously instantiated IEnumCERTVIEWATTRIBUTE object
while ( S_FALSE != pEnumAttr->Next( &Index ) )
{
    // retrieve the attribute name
    hr = pEnumAttr->GetName( &bstrAttribName );
    if ( FAILED( hr ) )
        printf("Failed GetName -  %x\n", hr );
    else
        printf("Attribute name: %S\n", bstrAttribName );
}

// free resources
if ( NULL != bstrAttribName )
    SysFreeString( bstrAttribName );

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certview.h.
Import Library: Use certidl.lib.

See Also

IEnumCERTVIEWATTRIBUTE::GetName, IEnumCERTVIEWATTRIBUTE::GetValue, IEnumCERTVIEWATTRIBUTE::Skip, IEnumCERTVIEWATTRIBUTE::Reset


IEnumCERTVIEWATTRIBUTE::Reset

[This is preliminary documentation and subject to change.]

The Reset method resets the IEnumCERTVIEWATTRIBUTE enumeration sequence to the beginning.

[VB] Reset();

[JAVA] Reset();

[C++] Reset();

Return Values

[C++] The return value is an HRESULT. A value of S_OK indicates success.

Remarks

Upon successful completion of this function, the IEnumCERTVIEWATTRIBUTE object will be positioned to the beginning of the object's attributes. To reference the first attribute after calling the IEnumCERTVIEWATTRIBUTE Reset method, call the IEnumCERTVIEWATTRIBUTE Next method. When a valid attribute is referenced by the IEnumCERTVIEWATTRIBUTE object, data can be retrieved through the IEnumCERTVIEWATTRIBUTE methods GetName and GetValue.

Example

// pEnumAttr is previously instantiated IEnumCERTVIEWATTRIBUTE object
HRESULT     hr;
LONG        Index;

hr = pEnumAttr->Reset();
if ( S_OK != hr )
    printf("Unable to reset pEnumAttr - %x\n", hr );
    // call appropriate error handler / exit routine
else
{
    // reset to beginning of attributes again
    while ( S_FALSE != pEnumAttr->Next( &Index ) )
    {
        // do something with each attribute
    }
}

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certview.h.
Import Library: Use certidl.lib.

See Also

IEnumCERTVIEWATTRIBUTE::Next, IEnumCERTVIEWATTRIBUTE::Skip


IEnumCERTVIEWATTRIBUTE::Skip

[This is preliminary documentation and subject to change.]

The Skip method skips a specified number of attributes in the IEnumCERTVIEWATTRIBUTE enumeration sequence.

[VB] Skip(
  Long celt
);

[JAVA] Skip(
  int celt
);

[C++] HRESULT Skip(
  LONG celt  // in
);

Parameters

celt
Number of attributes for the IEnumCertViewAttribute object to skip. A positive value for celt causes the IEnumCertViewAttribute object to skip forward in the enumeration sequence; a negative value for celt causes the IEnumCertViewAttribute object to skip backward in the enumeration sequence.

Return Values

[C++] The return value is an HRESULT. A value of S_OK indicates success. A return value of E_INVALIDARG indicates that a negative value for celt caused the IEnumCERTVIEWATTRIBUTE object's index to become less than zero.

Remarks

Upon successful completion of this function, the IEnumCERTVIEWATTRIBUTE object will have skipped celt attributes in the enumeration sequence. To access the attribute contents after a call to the IEnumCERTVIEWATTRIBUTE Skip method, call the IEnumCERTVIEWATTRIBUTE Next method.

The IEnumCERTVIEWATTRIBUTE object maintains an internal value representing the zero-based index of the attribute to be accessed when the IEnumCERTVIEWATTRIBUTE Next method is called. A call to the IEnumCERTVIEWATTRIBUTE Skip method causes this index to increase by celt if celt is positive, or to decrease by celt if celt is negative.

Negative values for celt are validated, and this function will fail if celt causes the index to be less than zero.

Positive values for celt are not validated, but if a positive value for celt causes the internal value to exceed the index for the last column in the enumeration sequence, a subsequent call to the IEnumCERTVIEWATTRIBUTE Next method will fail.

Example

HRESULT    hr;
LONG        Index;

// pEnumAttr is previously instantiated IEnumCERTVIEWATTRIBUTE object
// skip the next 5 attributes
hr = pEnumAttr->Skip( 5 );
if ( S_OK == hr )
{
    // get the next attribute
    hr = pEnumAttr->Next( &Index );
    if ( S_OK  == hr )
    {
        // do something with this attribute
        //…
    }
}

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certview.h.
Import Library: Use certidl.lib.

See Also

IEnumCERTVIEWATTRIBUTE:Next, IEnumCERTVIEWATTRIBUTE::Reset


IEnumCERTVIEWCOLUMN Interface

[This is preliminary documentation and subject to change.]

The IEnumCERTVIEWCOLUMN interface is used to access the data columns of a row in the Certificate Server's view. An IEnumCERTVIEWCOLUMN interface is instantiated through a call to the ICertView EnumCertViewColumn method, the IEnumCERTVIEWROW EnumCertViewColumn method,or the IEnumCERTVIEWCOLUMN Clone method.

The following methods are provided by the IEnumCERTVIEWCOLUMN interface.

Method | Description
Clone | Creates a copy of the IEnumCERTVIEWCOLUMN object.
GetMaxLength | Retrieves the maximum allowable length for the column data.
GetName | Retrieves the name of the column.
GetType | Retrieves the data type of the column.
GetValue | Retrieves the data value of the column.
IsIndexed | Reports whether column is indexed.
Next | Positions the IEnumCERTVIEWCOLUMN object to the next column.
Reset | Resets the IEnumCERTVIEWCOLUMN enumeration sequence to the beginning.
Skip | Skips a specified number of columns in the IEnumCERTVIEWCOLUMN enumeration sequence.


IEnumCERTVIEWCOLUMN::Clone

[This is preliminary documentation and subject to change.]

The Clone method creates a copy of the IEnumCERTVIEWCOLUMN object in its current state.

[VB] CEnumCERTVIEWCOLUMN Clone();

[JAVA] CEnumCERTVIEWCOLUMN Clone();

[C++] HRESULT Clone(
  IEnumCERTVIEWCOLUMN **ppenum  // out
);

Parameters

[C++] ppenum
Points to a pointer of IEnumCERTVIEWCOLUMN type; upon successful completion of this function, ppenum will point to the cloned object. This function will fail if ppenum is NULL.

Return Values

[VB][JAVA] The return value is a cloned IEnumCERTVIEWCOLUMN object.

[C++] The return value is an HRESULT. A value of S_OK indicates success.

Remarks

This function is used to clone the IEnumCERTVIEWCOLUMN object.

Example

// pEnumCol is previously instantiated IEnumCERTVIEWColumn object
IEnumCERTVIEWCOLUMN *    pEnumCol2 = NULL;
HRESULT    hr;
hr = pEnumCol->Clone( &pEnumCol2 );
if ( S_OK != hr )
    printf("Unable to clone IEnumCERTVIEWCOLUMN\n");
else
    // use cloned object as needed
    …
// done using cloned object, free memory
if ( NULL != pEnumCol2 )
    pEnumCol2->Release();

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certview.h.
Import Library: Use certidl.lib.


IEnumCERTVIEWCOLUMN::GetMaxLength

[This is preliminary documentation and subject to change.]

The GetMaxLength method retrieves the maximum allowable length for the column data.

[VB] Long GetMaxLength();

[JAVA] int GetMaxLength();

[C++] HRESULT GetMaxLength(
  LONG *pMaxLength  // out
);

Parameters

[C++] pMaxLength
Points to a LONG value that will contain the maximum allowable length for the column data. This function will fail if pMaxLength is NULL.

Return Values

[VB][JAVA] The return value is the maximum allowable length for the column data.

[C++] The return value is an HRESULT. A value of S_OK indicates success. Upon successful completion of this function, pMaxLength will point to the variable containing the maximum allowable length for the column data.

Remarks

This function is used to determine the maximum allowable data length for the column currently being referenced by the IEnumCERTVIEWCOLUMN object.

If the IEnumCERTVIEWCOLUMN object is not referencing a valid column, GetMaxLength will fail. Use the IEnumCERTVIEWCOLUMN Next method to reference a valid column.

Example

// pEnumCol is previously instantiated IEnumCERTVIEWColumn object
HRESULT    hr;
LONG       nLength;

// determine database length
hr = pEnumCol->GetMaxLength( &nLength );
if ( S_OK ==  hr )
    printf("max length is %d\n", nLength );

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certview.h.
Import Library: Use certidl.lib.

See Also

IEnumCERTVIEWCOLUMN::IsIndexed


IEnumCERTVIEWCOLUMN::GetName

[This is preliminary documentation and subject to change.]

The GetName method retrieves the name of the column.

[VB] String GetName();

[JAVA] java.lang.String GetName();

[C++] HRESULT GetName(
  BSTR *pstrOut  // out
);

Parameters

[C++] pstrOut
Pointer to a BSTR type that will contain the name of the column. This function will fail if pstrOut is NULL. It is the caller's responsibility to call SysFreeString when done with pstrOut.

Return Values

[VB][JAVA] The return value is a String representing the name of the column.

[C++] The return value is an HRESULT. A value of S_OK indicates success.

Remarks

This function is used to retrieve the nonlocalized name of the Certificate Server view column currently referenced by the IEnumCERTVIEWCOLUMN object.

If the IEnumCERTVIEWCOLUMN object is not referencing a valid column, GetName will fail. Use the IEnumCERTVIEWCOLUMN Next method to reference a valid column.

Example

BSTR       bstrColName = NULL;
HRESULT    hr;

// pEnumCol is previously instantiated IEnumCERTVIEWColumn object
hr = pEnumCol->GetName( &bstrColName );
if ( S_OK == hr )
    printf("Column name is %S\n", bstrColName );

// done processing, clear resources
if ( NULL != bstrColName )
    SysFreeString( bstrColName );

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certview.h.
Import Library: Use certidl.lib.

See Also

IEnumCERTVIEWCOLUMN::GetType, IEnumCERTVIEWCOLUMN::GetValue


IEnumCERTVIEWCOLUMN::GetType

[This is preliminary documentation and subject to change.]

The GetType method retrieves the data type of the column.

[VB] Long GetType();

[JAVA] int GetType();

[C++] HRESULT GetType(
  LONG *pIndexed  // out
);

Parameters

[C++] pIndexed
Pointer to LONG type that will denote the data type of the referenced view column. This function will fail if pIndexed is NULL.

Return Values

[VB][JAVA] The return value represents the data type of the column.

[C++] The return value is an HRESULT. A value of S_OK indicates success.

Remarks

This function is used to determine the data type of the Certificate Server view column currently referenced by the IEnumCERTVIEWCOLUMN object. The valid data types are listed in the following table.

Data type | Meaning
PROPTYPE_BINARY | Binary data
PROPTYPE_DATE | Date+Time
PROPTYPE_LONG | Signed long
PROPTYPE_STRING | Unicode String

If the IEnumCERTVIEWCOLUMN object is not referencing a valid column, GetType will fail. Use the IEnumCERTVIEWCOLUMN Next method to reference a valid column.

Example

LONG                     nType;
HRESULT                  hr;

// pEnumCol is previously instantiated IEnumCERTVIEWColumn object
hr = pEnumCol->GetType( &nType );
if ( S_OK ==  hr )
{
    switch ( nType )
    {
        case PROPTYPE_BINARY:
            printf("Type is Binary\n");
            break;
        case PROPTYPE_DATE:
            printf("Type is Date+Time\n");
            break;
        case PROPTYPE_LONG:
            printf("Type is Signed long\n");
            break;
        case PROPTYPE_STRING:
            printf("Type is Unicode String\n");
            break;
        default:
            printf("Type is unknown\n");
            break;
    }
}

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certview.h.
Import Library: Use certidl.lib.

See Also

IEnumCERTVIEWCOLUMN::GetName, IEnumCERTVIEWCOLUMN::GetValue


IEnumCERTVIEWCOLUMN::GetValue

[This is preliminary documentation and subject to change.]

The GetValue method retrieves the data value contained in the column.

[VB] Variant GetValue(
  Long Flags
);

[JAVA] com.ms.Variant GetValue(
  int Flags
);

[C++] HRESULT GetValue(
  LONG Flags,         // in
  VARIANT *pvarValue  // out
);

Parameters

Flags
Identifier that denotes the output format for the data stored in pvarValue. This can be one of the following values.
Flag | Meaning
CV_OUT_BASE64HEADER | BASE64 with begin/end
CV_OUT_BASE64 | BASE64 without begin/end
CV_OUT_BINARY | binary
CV_OUT_BASE64REQUESTHEADER | BASE64 with begin/end
CV_OUT_HEX | hex string
CV_OUT_HEXASCII | hex string with Ascii+address

[C++] pvarValue
Pointer to value of VARIANT type that will receive the data in the Certificate Server view's column. This function will fail if pvarValue is NULL. Upon successful completion of this function, pvarValue will point to a value of VARIANT type that will contain the data in the Certificate Server view's column. GetValue calls VariantClear on pvarValue, so in loop conditions the caller need not call VariantClear prior to calling GetValue. The caller is responsible for calling VariantInit before pvarValue is first used as a parameter by GetValue; the caller is also responsible for calling VariantClear when done with pvarValue (such as prior to exiting a function).

Return Values

[VB][JAVA] The return value is a Variant representing the data in the column.

[C++] The return value is an HRESULT. A value of S_OK indicates success.

Remarks

This function is used to retrieve the data in the column currently being referenced by the IEnumCERTVIEWCOLUMN object.

If the IEnumCERTVIEWCOLUMN object is not referencing a valid column, GetValue will fail. Use the IEnumCERTVIEWCOLUMN Next method to reference a valid column.

Example

HRESULT                  hr;
VARIANT                  var;
SYSTEMTIME               systime;

VariantInit( &var);

// pEnumCol is previously instantiated IEnumCERTVIEWColumn object
hr = pEnumCol->GetValue( CV_OUT_HEX, &var );
if ( FAILED (hr) )
{
    printf("Failed GetValue - %x\n", hr );
    goto error;
}
switch( var.vt )
{
    case VT_EMPTY:
        printf( "VT_EMPTY\n" );
        break;
    case VT_BSTR:
        printf("%S\n", var.bstrVal );
        break;
    case VT_DATE:
        VariantTimeToSystemTime( var.date, &systime );
        printf("%d.%d.%d %02d:%02d:%02d\n",
               systime.wMonth,
               systime.wDay,
               systime.wYear,
               systime.wHour,
               systime.wMinute,
               systime.wSecond );
        break;
    case VT_I2:
        printf("%d\n", var.iVal );
        break;
    case VT_I4:
        printf("%d\n", var.lVal );
        break;
    default:
        printf("type is:%i\n", var.vt );
        break;
}
// done processing, clear resources
VariantClear( &var );

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certview.h.
Import Library: Use certidl.lib.

See Also

IEnumCERTVIEWCOLUMN::GetName, IEnumCERTVIEWCOLUMN::GetType


IEnumCERTVIEWCOLUMN::IsIndexed

[This is preliminary documentation and subject to change.]

The IsIndexed method reports whether the column is indexed.

[VB] Long IsIndexed();

[JAVA] int IsIndexed();

[C++] HRESULT IsIndexed(
  LONG *pIndexed  // out
);

Parameters

[C++] pIndexed
Pointer to a LONG variable. This function will fail if pIndexed is NULL.

Return Values

[VB][JAVA] The return value is 1 is the column is indexed, or 0 otherwise.

[C++] The return value is an HRESULT. A value of S_OK indicates success. If the column is indexed, pIndex will point to a value of TRUE; if the column is not indexed, pIndex will point to a value of FALSE.

Remarks

This function is used to determine if a Certificate Server view's column is indexed.

If the IEnumCERTVIEWCOLUMN object is not referencing a valid column, ISIndexed will fail. Use the IEnumCERTVIEWCOLUMN Next method to reference a valid column.

Example

HRESULT    hr;
LONG       bIsindexed;

// pEnumCol is previously instantiated IEnumCERTVIEWColumn object
hr = pEnumCol->IsIndexed( &bIsindexed );
if ( S_OK == hr )
    printf( bIsindexed ? "Indexed\n" : "Not indexed\n");

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certview.h.
Import Library: Use certidl.lib.

See Also

IEnumCERTVIEWCOLUMN::GetMaxLength


IEnumCERTVIEWCOLUMN::Next

[This is preliminary documentation and subject to change.]

The Next method positions the IEnumCERTVIEWCOLUMN object to the next column.

[VB] Long Next();

[JAVA] int Next();

[C++] HRESULT Next(
  LONG *pIndex  // out
);

Parameters

[C++] pIndex
Pointer to variable that will contain the index value of the next column referenced by the IEnumCERTVIEWCOLUMN object. If there are no more columns to enumerate, this variable will be set to – 1. This function will fail if pIndex is NULL.

Return Values

[VB][JAVA] The return value is the index value of the next column that will be referenced by the IEnumCERTVIEWCOLUMN object. If there are no more rows to enumerate, the return value will be – 1.

[C++] The return value is an HRESULT. A value of S_OK indicates success and that the next column is now being referenced by the IEnumCERTVIEWCOLUMN object. If there are no more columns to enumerate, S_FALSE is returned, and pIndex will point to a value of – 1.

Remarks

Upon successful completion of this function, the Certificate Server view's IEnumCERTVIEWCOLUMN object will be referencing the next column. When the IEnumCERTVIEWCOLUMN is referencing a column, the column information can be retrieved through the IEnumCERTVIEWCOLUMN methods GetName, GetType, and GetValue.

Example

LONG       nLength;
LONG       nType;
LONG       bIsindexed;
LONG       Index;

HRESULT    hr;

BSTR       bstrColName = NULL;

// pEnumCol is previously instantiated IEnumCERTVIEWColumn object
// examine each column
while ( S_FALSE != pEnumCol->Next( &Index ) )
{
    // determine database length
    hr = pEnumCol->GetMaxLength( &nLength );
    if ( FAILED( hr ) )
    {
        printf("Failed GetMaxLength %x\n", hr);
        goto error;
    }

    // determine data type
    hr = pEnumCol->GetType( &nType );
    if ( FAILED( hr ) )
    {
        printf("Failed GetType %x\n", hr);
        goto error;
    }

    // determine if column is indexed
    hr = pEnumCol->IsIndexed( &bIsindexed );
    if ( FAILED( hr ) )
    {
        printf("Failed IsIndexed %x\n", hr);
        goto error;
    }

    // retrieve column name
    hr = pEnumCol->GetName( &bstrColName );
    if ( FAILED( hr ) )
    {
        printf("Failed GetName %x\n", hr);
        goto error;
    }

    // print this column's info on one line
    // print name and length
    printf("Column %S has max length %d",
            bstrColName,
            nLength );

    // print data type
    switch ( nType )
    {
        case PROPTYPE_BINARY:
            printf(" Type is Binary");
            break;
        case PROPTYPE_DATE:
            printf(" Type is Date+Time");
            break;
        case PROPTYPE_LONG:
            printf(" Type is Signed long");
            break;
        case PROPTYPE_STRING:
            printf(" Type is Unicode String");
            break;
        default:
            printf(" Type is unknown");
            break;
    }

    // print index status
    printf( bIsindexed ? " Indexed" : " Not indexed");
    // print new line marker
    printf("\n");

}

error:

// done processing, clear resources
if ( NULL != bstrColName )
    SysFreeString( bstrColName );

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certview.h.
Import Library: Use certidl.lib.

See Also

IEnumCERTVIEWCOLUMN::GetName, IEnumCERTVIEWCOLUMN::GetType, IEnumCERTVIEWCOLUMN::GetValue


IEnumCERTVIEWCOLUMN::Reset

[This is preliminary documentation and subject to change.]

The Reset method resets the IEnumCERTVIEWCOLUMN enumeration sequence to the beginning.

[VB] Reset();

[JAVA] Reset();

[C++] HRESULT Reset();

Return Values

[C++] The return value is an HRESULT. A value of S_OK indicates success.

Remarks

Upon successful completion of this function, the IEnumCERTVIEWCOLUMN object will be positioned to the beginning the IEnumCERTVIEWCOLUMN object's columns. To access the data in the first column after calling the IEnumCERTVIEWCOLUMN Reset method, call the IEnumCERTVIEWCOLUMN Next method. When a valid column is being referenced by the IEnumCERTVIWCOLUMN object, data can be retrieved through calls to the IEnumCERTVIEWCOLUMN methods GetName, GetType, and GetValue.

Example

// pEnumCol is previously instantiated IEnumCERTVIEWColumn object
HRESULT    hr;
LONG        Index;
hr = pEnumCol->Reset();
if ( S_OK != hr )
    printf("Unable to reset pEnumCol\n");
    // call appropriate error handler / exit routine
else
{
    // now at the beginning of the columns
    // enumerate each column
    while ( S_FALSE != pEnumCol->Next( &Index ) )
    {
        // do something with each column
    }
}

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certview.h.
Import Library: Use certidl.lib.

See Also

IEnumCERTVIEWCOLUMN::Next, IEnumCERTVIEWCOLUMN::Skip


IEnumCERTVIEWCOLUMN::Skip

[This is preliminary documentation and subject to change.]

The Skip method skips a specified number of columns in the IEnumCERTVIEWCOLUMN enumeration sequence.

[VB] Skip(
  Long celt
);

[JAVA] Skip(
  int celt
);

[C++] HRESULT Skip(
  LONG celt  // in
);

Parameters

celt
Number of columns for the IEnumCERTVIEWCOLUMN object to skip. A positive value for celt causes the IEnumCERTVIEWCOLUMN object to skip forward in the enumeration sequence; a negative value for celt causes the IEnumCERTVIEWCOLUMN object to skip backward in the enumeration sequence.

Return Values

[C++] The return value is an HRESULT. A value of S_OK indicates success. A return value of E_INVALIDARG indicates that a negative value for celt caused the IEnumCERTVIEWCOLUMN object's index to become less than zero.

Remarks

Upon successful completion of this function, the IEnumCERTVIEWCOLUMN object will have skipped celt columns in the enumeration sequence. To access the column contents after a call to the IEnumCERTVIEWCOLUMN Skip method, call the IEnumCERTVIEWCOLUMN Next method.

The IEnumCERTVIEWCOLUMN object maintains an internal value representing the zero-based index of the column to be accessed when the IEnumCERTVIEWCOLUMN Next method is called. A call to the IEnumCERTVIEWCOLUMN Skip method causes this index to increase by celt if celt is positive, or to decrease by celt if celt is negative.

Negative values for celt are validated, and this function will fail if celt causes the index to be less than zero.

Positive values for celt are not validated, but if a positive value for celt causes the internal value to exceed the index for the last column in the enumeration sequence, a subsequent call to the IEnumCERTVIEWCOLUMN Next method will fail.

Example

HRESULT    hr;
LONG        Index;

// pEnumCol is previously instantiated IEnumCERTVIEWColumn object
// skip the next 5 columns
hr = pEnumCol->Skip( 5 );
if ( S_OK == hr )
{
    // get the next column
    hr = pEnumCol->Next( &Index );
    if ( S_OK  == hr )
    {
        // do something with this column
        //…
    }
}

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certview.h.
Import Library: Use certidl.lib.

See Also

IEnumCERTVIEWCOLUMN:Next, IEnumCERTVIEWCOLUMN::Reset


IEnumCERTVIEWEXTENSION Interface

[This is preliminary documentation and subject to change.]

The IEnumCERTVIEWEXTENSION object is used to access the certificate extension data for a row in the Certificate Server view. An IEnumCERTVIEWEXTENSION interface is instantiated through a call to IEnumCERTVIEWROW::EnumCertViewExtension.

The following methods are provided by the IEnumCERTVIEWEXTENSION interface.

Method | Description
Clone | Creates a copy of the IEnumCERTVIEWEXTENSION object.
GetFlags | Retrieves the policy and origin flags of the extension.
GetName | Retrieves the name of the extension.
GetValue | Retrieves the extension value.
Next | Positions the IEnumCERTVIEWEXTENSION object to the next extension.
Reset | Resets the IEnumCERTVIEWEXTENSION enumeration sequence to the beginning.
Skip | Skips a specified number of extensions in the IEnumCERTVIEWEXTENSION enumeration sequence.


IEnumCERTVIEWEXTENSION::Clone

[This is preliminary documentation and subject to change.]

The Clone method creates a copy of the IEnumCERTVIEWEXTENSION object in its current state.

[VB] CEnumCERTVIEWEXTENSION Clone();

[JAVA] IEnumCERTVIEWEXTENSION Clone(
  OUT IEnumCERTVIEWEXTENSION **ppenum
);

[C++] HRESULT Clone(
  IEnumCERTVIEWEXTENSION **ppenum  // out
);

Parameters

[C++] ppenum
Points to a pointer of IEnumCERTVIEWEXTENSION type; upon successful completion of this function, ppenum will point to the cloned object.. This function will fail if ppenum is NULL.

Return Values

[VB][JAVA] The return value is a cloned IEnumCERTVIEWEXTENSION object.

[C++] The return value is an HRESULT. A value of S_OK indicates success.

Remarks

This function is used to clone the IEnumCERTVIEWEXTENSION object.

Example

IEnumCERTVIEWEXTENSION *   pEnumExt2 = NULL;
HRESULT                    hr;

// pEnumExt is previously instantiated IEnumCERTVIEWEXTENSION object
hr = pEnumExt->Clone( &pEnumExt2 );
if ( S_OK != hr )
    printf("Unable to clone IEnumCERTVIEWEXTENSION\n");
else
    // use cloned object as needed
    //…

// done using cloned object, free memory
if ( NULL != pEnumExt2 )
    pEnumExt2->Release();

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certview.h.
Import Library: Use certidl.lib.


IEnumCERTVIEWEXTENSION::GetFlags

[This is preliminary documentation and subject to change.]

The GetFlags method retrieves the policy and origin flags of the extension. Both the policy and origin flags are stored in one variable, and bitmasks are provided to retrieve the individual values.

[VB] Long GetFlags();

[JAVA] int GetFlags();

[C++] HRESULT GetFlags(
  LONG *pFlags  // out
);

Parameters

[C++] pFlags
Pointer to a LONG type that will contain the policy and origin flags of the extension. This function will fail if pFlags is NULL.

Return Values

[VB][JAVA] The return value represents the policy and origin values of the extension.

[C++] The return value is an HRESULT. A value of S_OK indicates success.

Remarks

This function is used to determine both the policy and origin flags of the extension currently referenced by the IEnumCERTVIEWEXTENSION object.

The bitmasks in the following table can be used to determine the individual values for the policy and origin flags.

Bitmask | Usage
EXTENSION_POLICY_MASK | Determines policy value
EXTENSION_ORIGIN_MASK | Determines origin value

If the IEnumCERTVIEWEXTENSION object is not referencing a valid extension, GetFlags will fail. Use the IEnumCERTVIEWEXTENSION Next method to reference a valid extension.

Example

HRESULT    hr;
LONG       ExtFlags;

// pEnumExt is previously instantiated IEnumCERTVIEWEXTENSION object
hr = pEnumExt->GetFlags(&ExtFlags);
if ( S_OK != hr )
    printf("Failed GetFlags call!\n");
else
{
    switch ( ExtFlags & EXTENSION_POLICY_MASK )
    {
        case EXTENSION_CRITICAL_FLAG:
            printf("Extension critical\n");
            break;
        case EXTENSION_DISABLE_FLAG:
            printf("Extension disabled\n");
            break;
        case 0:
            printf("No extension policy set\n");
            break;
        default:
            printf("Unknown extension policy flag\n");
            break;
    }
    switch ( ExtFlags & EXTENSION_ORIGIN_MASK )
    {
        case EXTENSION_ORIGIN_REQUEST:
            printf("Extension originated by Request\n");
            break;
        case EXTENSION_ORIGIN_POLICY:
            printf("Extension originated by Policy\n");
            break;
        case EXTENSION_ORIGIN_ADMIN:
            printf("Extension originated by Admin\n");
            break;
        case EXTENSION_ORIGIN_SERVER:
            printf("Extension originated by Server\n");
            break;
        default:
            printf("Unknown extension origin\n");
            break;
    }
}

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certview.h.
Import Library: Use certidl.lib.

See Also

IEnumCERTVIEWEXTENSION::GetName, IEnumCERTVIEWEXTENSION::GetValue


IEnumCERTVIEWEXTENSION::GetName

[This is preliminary documentation and subject to change.]

The GetName method retrieves the name of the extension.

[VB] String GetName();

[JAVA] java.lang.String GetName(
);

[C++] HRESULT GetName(
  BSTR *pstrOutName  // out
);

Parameters

[C++] pstrOutName
Pointer to a value of BSTR type that will contain the name of the extension. This function will fail if pstrOutName is NULL. It is the caller's responsibility to call SysFreeString when done with pstrOutName.

Return Values

[VB][JAVA] The return value is a String representing the name of the column.

[C++] The return value is an HRESULT. A value of S_OK indicates success.

Remarks

This function is used to retrieve the name of the extension currently referenced by the IEnumCERTVIEWEXTENSION object.

If the IEnumCERTVIEWEXTENSION object is not referencing a valid extension, GetName will fail. Use the IEnumCERTVIEWEXTENSION Next method to reference a valid extension.

Example

BSTR    bstrExtName = NULL;

// pEnumExt is previously instantiated IEnumCERTVIEWEXTENSION object
hr = pEnumExt->GetName(&bstrExtName);
if ( S_OK == hr )
    printf("Extentsion name is: %S\n", bstrExtName );
else
    printf("GetName failed: %x\n", hr );

// free memory when done
if ( NULL != bstrExtName )
    SysFreeString( bstrExtName );

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certview.h.
Import Library: Use certidl.lib.

See Also

IEnumCERTVIEWEXTENSION::GetFlags, IEnumCERTVIEWEXTENSION::GetValue


IEnumCERTVIEWEXTENSION::GetValue

[This is preliminary documentation and subject to change.]

The GetValue method retrieves the extension value.

[VB] Variant GetValue(
  Long Type,
  Long Flags
);

[JAVA] com.ms.Variant GetValue(
  int Type,
  int Flags
);

[C++] HRESULT GetValue(
  LONG Type,          // in
  LONG Flags,         // in
  VARIANT *pvarValue  // out
);

Parameters

Type
Data type identifier for the returned data in pvarValue. Use of this flag allows the caller to specify that the extension data be decoded prior to being returned in pvarValue. Type can be one of the following values. (If PROPTYPE_BINARY is specified, the data is not decoded but instead returned in its raw format.).
Data type | Meaning
PROPTYPE_BINARY | Binary data
PROPTYPE_DATE | Date+Time
PROPTYPE_LONG | Signed long
PROPTYPE_STRING | Unicode String

Flags
Identifier that denotes the output format for the data stored in pvarValue. This can be one of the following values.
Flag | Meaning
CV_OUT_BASE64HEADER | BASE64 with begin/end
CV_OUT_BASE64 | BASE64 without begin/end
CV_OUT_BINARY | binary
CV_OUT_BASE64REQUESTHEADER | BASE64 with begin/end
CV_OUT_HEX | hex string
CV_OUT_HEXASCII | hex string with Ascii+address

[C++] pvarValue
Pointer to value of VARIANT type that will receive the data for the currently referenced extension. This function will fail if pvarValue is NULL.Upon successful completion of this function, pvarValue will point to a value of VARIANT type that will contain the extension data currently referenced by the IEnumCERTVIEWEXTENSION object. GetValue calls VariantClear on pvarValue, so in loop conditions the caller need not call VariantClear prior to calling GetValue. The caller is responsible for calling VariantInit before pvarValue is first used as a parameter by GetValue; the caller is also responsible for calling VariantClear when done with pvarValue.

Return Values

[VB][JAVA] The return value is a Variant representing the data in the extension.

[C++] The return value is an HRESULT. A value of S_OK indicates success.

Remarks

This function is used to retrieve the data in the extension currently being referenced by the IEnumCERTVIEWEXTENSION object.

If the IEnumCERTVIEWEXTENSION object is not referencing a valid extension, GetValue will fail. Use the IEnumCERTVIEWEXTENSION Next method to reference a valid extension.

Example

VARIANT         var;
LONG            Index;
HRESULT         hr;
SYSTEMTIME      systime;

VariantInit( &var );

// Enumerate each extension
// pEnumExt is previously instantiated IEnumCERTVIEWEXTENSION object
while ( S_FALSE != pEnumExt->Next( &Index ) )
{
    hr = pEnumExt->GetValue( CV_OUT_HEX, &var );
    if ( FAILED( hr ))
    {
        printf("Failed GetValue - %x\n", hr );
        break;
    }
    switch( var.vt )
    {
        case VT_EMPTY:
            printf( "VT_EMPTY\n" );
            break;
        case VT_BSTR:
            printf("BSTR:%S\n", var.bstrVal );
            break;
        case VT_DATE:
            VariantTimeToSystemTime( var.date, &systime );
            printf("%d.%d.%d %02d:%02d:%02d\n",
                   systime.wMonth,
                   systime.wDay,
                   systime.wYear,
                   systime.wHour,
                   systime.wMinute,
                   systime.wSecond );
            break;
        case VT_I2:
            printf("%d\n", var.iVal );
            break;
        case VT_I4:
            printf("%d\n", var.lVal );
            break;
        default:
            printf("type is:%i\n", var.vt );
            break;
    }
}
// free resources
VariantClear( &var );

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certview.h.
Import Library: Use certidl.lib.

See Also

IEnumCERTVIEWEXTENSION::GetFlags, IEnumCERTVIEWEXTENSION::GetName


IEnumCERTVIEWEXTENSION::Next

[This is preliminary documentation and subject to change.]

The Next method positions the IEnumCERTVIEWEXTENSION object to the next extension.

[VB] Long Next();

[JAVA] int Next(
);

[C++] HRESULT Next(
  LONG *pIndex   // out
);

Parameters

[C++] pIndex
Pointer to LONG variable that will contain the index value of the next extension referenced. If there are no more extensions to enumerate, this variable will be set to – 1. This function will fail if pIndex is NULL.

Return Values

[VB][JAVA] The return value is the index value of the next column that will be referenced by the IEnumCERTVIEWEXTENSION object. If there are no more extensions to enumerate, the return value will be – 1.

[C++] The return value is an HRESULT. A value of S_OK indicates success and that the next extension is now being referenced. If there are no more attributes, S_FALSE is returned, and pIndex will point to a value of – 1.

Remarks

Upon successful completion of this function, the IEnumCERTVIEWEXTENSION object will be referencing the next extension. When the extension is referenced, the extension name, flags, and value can be accessed through the IEnumCERTVIEWEXTENSION methods GetName, GetFlags, and GetValue.

Example

LONG         Index;
LONG         nCount;

// determine the number of extensions
nCount = 0;
// pEnumExt is previously instantiated IEnumCERTVIEWEXTENSION object
while ( S_FALSE != pEnumExt->Next( &Index ) )
{
    nCount++;
}
printf("Number of extensions is %d\n", nCount );

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certview.h.
Import Library: Use certidl.lib.

See Also

IEnumCERTVIEWEXTENSION::GetName, IEnumCERTVIEWEXTENSION::GetValue, IEnumCERTVIEWEXTENSION::Reset, IEnumCERTVIEWEXTENSION::Skip


IEnumCERTVIEWEXTENSION::Reset

[This is preliminary documentation and subject to change.]

The Reset method resets the IEnumCERTVIEWEXTENSION enumeration sequence to the beginning.

[VB] Reset();

[JAVA] Reset();

[C++] HRESULT Reset();

Return Values

[C++] The return value is an HRESULT. A value of S_OK indicates success.

Remarks

Upon successful completion of this function, the IEnumCERTVIEWEXTENSION object will be positioned to the beginning of the object's extensions. To reference the first extension after calling the IEnumCERTVIEWEXTENSION Reset method, call the IEnumCERTVIEWEXTENSION Next method. When a valid extension is referenced by the IEnumCERTVIEWEXTENSION object, information can be retrieved through calls to the IEnumCERTVIEWEXTENSION methods GetFlags, GetName, and GetValue.

Example

HRESULT     hr;
LONG        Index;

// pEnumExt is previously instantiated IEnumCERTVIEWEXTENSION object
hr = pEnumExt->Reset();
if ( S_OK != hr )
    printf("Unable to reset pEnumExt - %x\n", hr );
    // call appropriate error handler / exit routine
else
{
    // reset to beginning of extensions again
    while ( S_FALSE != pEnumExt->Next( &Index ) )
    {
        // do something with each extension
    }
}

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certview.h.
Import Library: Use certidl.lib.

See Also

IEnumCERTVIEWEXTENSION::Next, IEnumCERTVIEWEXTENSION::Skip


IEnumCERTVIEWEXTENSION::Skip

[This is preliminary documentation and subject to change.]

The Skip method skips a specified number of extensions in the IEnumCERTVIEWEXTENSION enumeration sequence.

[VB] Skip(
  Long celt
);

[JAVA] Skip(
  int celt
);

[C++] HRESULT Skip(
  LONG celt  // in
);

Parameters

celt
Number of extensions for the IEnumCERTVIEWEXTENSION object to skip. A positive value for celt causes the IEnumCERTVIEWEXTENSION object to skip forward in the enumeration sequence; a negative value for celt causes the IEnumCERTVIEWEXTENSION object to skip backward in the enumeration sequence.

Return Values

[C++] The return value is an HRESULT. A value of S_OK indicates success. A return value of E_INVALIDARG indicates that a negative value for celt caused the IEnumCERTVIEWEXTENSION object's index to become less than zero.

Remarks

Upon successful completion of this function, the IEnumCERTVIEWEXTENSION object will have skipped celt extensions in the enumeration sequence. To access the extension contents after a call to the IEnumCERTVIEWEXTENSION Skip method, call the IEnumCERTVIEWEXTENSION Next method.

The IEnumCERTVIEWEXTENSION object maintains an internal value representing the zero-based index of the extension to be accessed when the IEnumCERTVIEWEXTENSION Next method is called. A call to the IEnumCERTVIEWEXTENSION Skip method causes this index to increase by celt if celt is positive, or to decrease by celt if celt is negative.

Negative values for celt are validated, and this function will fail if celt causes the index to be less than zero.

Positive values for celt are not validated, but if a positive value for celt causes the internal value to exceed the index for the last column in the enumeration sequence, a subsequent call to the IEnumCERTVIEWEXTENSION Next method will fail.

Example

HRESULT    hr;
LONG       Index;

// pEnumExt is previously instantiated IEnumCERTVIEWEXTENSION object
// skip the next 5 extensions
hr = pEnumExt->Skip( 5 );
if ( S_OK == hr )
{
    // get the next extension
    hr = pEnumExt->Next( &Index );
    if ( S_OK == hr )
    {
        // do something with this extension
        //…
    }
}

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certview.h.
Import Library: Use certidl.lib.

See Also

IEnumCERTVIEWEXTENSION::Next, IEnumCERTVIEWEXTENSION::Reset


IEnumCERTVIEWROW Interface

[This is preliminary documentation and subject to change.]

The IEnumCERTVIEWROW interface is used to enumerate the rows of the Certificate Server view, allowing access to the data. An IEnumCERTVIEWROW interface is instantiated through a call to the ICertView OpenView method or through a call to the IEnumCERTVIEWROW Clone method. Once a row is enumerated, an enumerator to the column data can be instantiated through the IEnumCERTVIEWROW EnumCertViewColumn method. IEnumCERTVIEWROW also provides methods to retrieve a certificate's attributes and extensions.

The following methods are provided by the IEnumCERTVIEWROW interface.

Method | Description
Clone | Creates a copy of the IEnumCERTVIEWROW object.
EnumCertViewAttribute | Obtains a pointer to the IEnumCERTVIEWATTRIBUTE interface.
EnumCertViewColumn | Obtains a pointer to the IEnumCERTVIEWCOLUMN interface.
EnumCertViewExtension | Obtains a pointer to the IEnumCERTVIEWEXTENSION interface.
Next | Positions the IEnumCERTVIEWROW object to the next row.
Reset | Resets the IEnumCERTVIEWROW enumeration sequence to the beginning.
Skip | Skips a specified number of rows in the IEnumCERTVIEWROW enumeration sequence.


IEnumCERTVIEWROW::Clone

[This is preliminary documentation and subject to change.]

The Clone method creates a copy of the IEnumCERTVIEWROW object in its current state.

[VB] CEnumCERTVIEWROW Clone();

[JAVA] CEnumCERTVIEWROW Clone();

[C++] HRESULT Clone(
  IEnumCERTVIEWROW **ppenum    // out
);

Parameters

[C++] ppenum
Pointer to a pointer of IEnumCERTVIEWROW type; upon successful completion of this function, ppenum will point to the cloned object. This function will fail if ppenum is NULL.

Return Values

[VB][JAVA] The return value is a cloned IEnumCERTVIEWROW object.

[C++] The return value is an HRESULT. A value of S_OK indicates success.

Remarks

This function is used to clone the IEnumCERTVIEWROW object.

Example

// pEnumRow is previously instantiated IEnumCERTVIEWROW object
HRESULT    hr;
IEnumCERTVIEWROW *    pEnumRow2 = NULL;

hr = pEnumRow->Clone( &pEnumRow2 );
if ( S_OK != hr )
    printf("Unable to clone IEnumCERTVIEWROW - %x\n", hr);
else
    // use cloned object as needed
    …
// done using cloned object, free memory
if ( NULL != pEnumRow2 )
    pEnumRow2->Release();

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certview.h.
Import Library: Use certidl.lib.


IEnumCERTVIEWROW::EnumCertViewAttribute

[This is preliminary documentation and subject to change.]

The EnumCertViewAttribute method obtains an instance of the IEnumCERTVIEWATTRIBUTE object.

[VB] CEnumCERTVIEWATTRIBUTE EnumCertViewAttribute(
  Long Flags
);

[JAVA] CEnumCERTVIEWATTRIBUTE EnumCertViewAttribute(
  int Flags
);

[C++] HRESULT EnumCertViewAttribute(
  LONG Flags,                      // in
  IEnumCERTVIEWATTRIBUTE **ppenum  // out
);

Parameters

Flags
LONG value. Must be zero.
[C++] ppenum
Pointer to pointer of IEnumCERTVIEWATTRIBUTE type. Upon successful completion of this function, ppenum will point to a pointer of IEnumCERTVIEWATTRIBUTE type.

Return Values

[VB][JAVA] The returned object is a IEnumCERTVIEWATTRIBUTE object.

[C++] The return value is an HRESULT. A value of S_OK indicates success.

Remarks

The IEnumCERTVIEWATTRIBUTE object can be used to enumerate the certificate's attributes.

Example

// pEnumRow is previously instantiated pointer to IEnumCERTVIEWROW
HRESULT                     hr;
LONG                        Index;
IEnumCERTVIEWATTRIBUTE *    pEnumAttr = NULL;

// obtain enumerator for attributes
hr = pEnumRow->EnumCertViewAttribute( 0, &pEnumAttr );
if ( FAILED( hr ))
{
    printf("Failed EnumCertViewAttribute - %x\n", hr );
    goto error;
}
// enumerate each attribute
while ( S_FALSE != pEnumAttr->Next( &Index ) )
{
    // do something with this attribute
    //…
}
error:

// free resources
if ( NULL != pEnumAttr )
    pEnumAttr->Release();

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certview.h.
Import Library: Use certidl.lib.

See Also

IEnumCERTVIEWATTRIBUTE Interface


IEnumCERTVIEWROW::EnumCertViewColumn

[This is preliminary documentation and subject to change.]

The EnumCertViewColumn method obtains an instance of the IEnumCERTVIEWCOLUMN object.

[VB] CEnumCERTVIEWCOLUMN EnumCertViewColumn();

[JAVA] CEnumCERTVIEWCOLUMN EnumCertViewColumn();

[C++] HRESULT EnumCertViewColumn(
  IEnumCERTVIEWCOLUMN **ppenum  // out
);

Parameters

[C++] ppenum
Pointer to pointer of IEnumCERTVIEWCOLUMN type.

Return Values

[VB][JAVA] The return value is a IEnumCERTVIEWCOLUMN object.

[C++] The return value is an HRESULT. A value of S_OK indicates success.

Remarks

The IEnumCERTVIEWCOLUMN object is used to enumerate the view's columns for the purposes of retrieving data elements.

Example

// pEnumRow is previously instantiated pointer to IEnumCERTVIEWROW
HRESULT                  hr;
LONG                     Index;
IEnumCERTVIEWCOLUMN *    pEnumCol = NULL;
// obtain enumerator for columns
hr = pEnumRow->EnumCertViewColumn( &pEnumCol );
if ( FAILED( hr ))
{
    printf("Failed EnumCertViewColumn - %x\n", hr );
    goto error;
}
// enumerate each column
while ( S_FALSE != pEnumCol->Next( &Index ) )
{
    // do something with this column
    //…
}
error:

// free resources
if ( NULL != pEnumCol )
    pEnumCol->Release();

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certview.h.
Import Library: Use certidl.lib.

See Also

IEnumCERTVIEWCOLUMN Interface


IEnumCERTVIEWROW::EnumCertViewExtension

[This is preliminary documentation and subject to change.]

The EnumCertViewExtension method obtains an instance of the IEnumCERTVIEWEXTENSION object.

[VB] CEnumCERTVIEWEXTENSION EnumCertViewExtension(
  Long Flags
);

[JAVA] CEnumCERTVIEWEXTENSION EnumCertViewExtension(
  int Flags
);

[C++] EnumCertViewExtension(
  LONG Flags,                     // in
  IEnumCERTVIEWEXTENSION **ppenum // out
);

Parameters

Flags
LONG value. Must be zero.
[C++] ppenum
Pointer to pointer of IEnumCERTVIEWEXTENSION type.

Return Values

[VB][JAVA] The return value is a IEnumCERTVIEWEXTENSION object.

[C++] The return value is an HRESULT. A value of S_OK indicates success.

Remarks

The IEnumCERTVIEWEXTENSION object is used to enumerate the view's extensions.

Example

// pEnumRow is previously instantiated pointer to IEnumCERTVIEWROW
LONG                        Index;
HRESULT                     hr;
IEnumCERTVIEWEXTENSION *    pEnumExt = NULL;
// obtain enumerator for extensions
hr = pEnumRow->EnumCertViewExtension( 0, &pEnumExt );
if ( FAILED( hr ))
{
    printf("Failed EnumCertViewExtension - %x\n", hr );
    goto error;
}
// enumerate each extension
while ( S_FALSE != pEnumExt->Next( &Index ) )
{
    // do something with this extension
    //…
}
error:

// free resources
if ( NULL != pEnumExt )
    pEnumExt->Release();

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certview.h.
Import Library: Use certidl.lib.

See Also

IEnumCERTVIEWEXTENSION Interface


IEnumCERTVIEWROW::Next

[This is preliminary documentation and subject to change.]

The Next method positions the IEnumCERTVIEWROW object to the next row.

[VB] Long Next();

[JAVA] int Next();

[C++] HRESULT Next(
  LONG *pIndex   // out
);

Parameters

[C++] pIndex
Pointer to LONG variable that will contain the index value of the next row that will be referenced by the IEnumCERTVIEWROW object. If there are no more rows to enumerate, this variable will be set to – 1. This function will fail if pIndex is NULL.

Return Values

[VB][JAVA] The return value is the index value of the next row that will be referenced by the IEnumCERTVIEWROW object. If there are no more rows to enumerate, the return value will be – 1.

[C++] The return value is an HRESULT. A value of S_OK indicates success and that the next row is now being referenced by the IEnumCERTVIEWROW object. If there are no more rows to enumerate, S_FALSE is returned, and pIndex will point to a value of – 1.

Remarks

Upon successful completion of this function, the IEnumCERTVIEWROW object will have moved to the next data row. Once the row is referenced, the column data can be retrieved through calls to IEnumCERTVIEWCOLUMN.

Example

// pEnumRow is previously instantiated pointer to IEnumCERTVIEWROW
LONG                 Index;
LONG                 nCount;

// ensure enumerator is at first row
if ( FAILED (pEnumRow->Reset()))
    printf("Failed to Reset\n");
else
{
    nCount = 0;
    // count the database records by enumerating the rows
    while ( S_FALSE != pEnumRow->Next( &Index ) )
        nCount++;
    // display number of records
    printf("Number of records is %d\n", nCount );
}

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certview.h.
Import Library: Use certidl.lib.

See Also

IEnumCERTVIEWROW::Reset, IEnumCERTVIEWROW::Skip


IEnumCERTVIEWROW::Reset

[This is preliminary documentation and subject to change.]

The Reset method resets the IEnumCERTVIEWROW enumeration sequence to the beginning.

[VB] Reset();

[JAVA] Reset();

[C++] HRESULT Reset();

Return Values

[C++] The return value is an HRESULT. A value of S_OK indicates success.

Remarks

Upon successful completion of this function, the IEnumCERTVIEWROW object will be positioned to the beginning the Certificate Server view's rows. To access the data in the first row after calling the IEnumCERTVIEWROW Reset method, call the IEnumCERTVIEWROW Next method. After a valid row has been referenced by the IEnumCERTVIEWROW object, data can be retrieved through calls to IEnumCERTVIEWCOLUMN.

Example

// pEnumRow is previously instantiated pointer to IEnumCERTVIEWROW
HRESULT              hr;
LONG                 Index;

// ensure enumerator is at first row
hr = pEnumRow->Reset();
if ( FAILED( hr ) )
    printf("Failed to Reset\n");
else
{
    printf("Reset to beginning\n");
    // retrieve first record
    hr = pEnumRow->Next( &Index );
    // examine hr for success and process row
    // ...
}

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certview.h.
Import Library: Use certidl.lib.

See Also

IEnumCERTVIEWROW::Next, IEnumCERTVIEWROW::Skip


IEnumCERTVIEWROW::Skip

[This is preliminary documentation and subject to change.]

The Skip method skips a specified number of rows in the IEnumCERTVIEWROW enumeration sequence.

[VB] Skip(
  Long celt
);

[JAVA] Skip(
  int celt
);

[C++] HRESULT Skip(
  IN LONG celt
);

Parameters

celt
Number of rows for the IEnumCERTVIEWROW object to skip. A positive value for celt causes the IEnumCERTVIEWROW object to skip forward in the enumeration sequence; a negative value for celt causes the IEnumCERTVIEWROW object to skip backward in the enumeration sequence.

Return Values

[C++] The return value is an HRESULT. A value of S_OK indicates success. A return value of E_INVALIDARG indicates that a negative value for celt caused the IEnumCERTVIEWROW object's index to become less than zero.

Remarks

Upon successful completion of this function, the IEnumCERTVIEWROW object will have skipped celt rows in the enumeration sequence. To access the row contents after a call to the IEnumCERTVIEWROW Skip method, call the IEnumCERTVIEWROW Next method.

The IEnumCERTVIEWROW object maintains an internal value representing the zero-based index of the row to be accessed when the IEnumCERTVIEWROW Next method is called. A call to the IEnumCERTVIEWROW Skip method causes this index to increase by celt if celt is positive, or to decrease by celt if celt is negative.

Negative values for celt are validated, and this function will fail if celt causes the index to be less than zero.

Positive values for celt are not validated, but if a positive value for celt causes the internal value to exceed the index for the last row in the enumeration sequence, a subsequent call to the IEnumCERTVIEWROW Next method will fail.

Example

// pEnumRow is previously instantiated pointer to IEnumCERTVIEWROW
HRESULT     hr;
LONG        Index;
// reposition the row enumerator to the beginning of the rows
hr = pEnumRow->Reset();
if (FAILED( hr ))
{
    printf("Unable to reset pEnumRow\n");
    goto error;
}
// skip some rows
hr = pEnumRow->Skip( 5 );
if ( FAILED( hr ) )
{
    printf("Unable to skip rows\n");
    goto error;
}

// get the next row
hr = pEnumRow->Next( &Index );
if ( S_OK == hr )
{
    // do something with this row
    …
}

error:

if ( NULL != pEnumRow )
    pEnumRow->Release();

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in certview.h.
Import Library: Use certidl.lib.

See Also

IEnumCERTVIEWROW:Next, IEnumCERTVIEWROW::Reset


Writing Custom Policy Modules

Policy modules are programs that use Automation to communicate with the certificate server. They receive requests from the certificate server, evaluate those requests, and specify optional properties of the certificate that will be built to fulfill the request.

You can write policy modules in C/C++, VB or Java. The required Microsoft compiler releases are Microsoft® Visual C++® version 5.0, Microsoft Visual Basic® version 5.0, and Microsoft Visual J++™ version 1.1.

The VerifyRequest method must be available from an Automation object that will be referenced as "CertificateAuthority.Policy."

Policy modules can also import the following methods exported by Certif.tlb and Certif.dll:

  • GetRequestProperty
  • GetCertificateProperty
  • SetCertificateProperty
  • GetCertificateExtension
  • SetCertificateExtension

These imports should be available from an Automation server and can be referenced with the format <VBvarname>.GetRequestProperty.

For further information, please see the following topics:

  • Setting Certificate Properties
  • Referencing Properties or Extensions
  • Data Types Supported by Policy Modules
  • Writing Policy Modules in Visual Basic
  • Visual Basic Policy Module Sample Code
  • Policy Module Technical Notes


Setting Certificate Properties

The policy module interface includes two methods for setting certificate properties and extensions, SetCertificateProperty and SetCertificateExtension. With these method calls, any of the properties or extensions of a certificate can be set via the policy module. Here is a Microsoft® Visual Basic® example of how each of these method calls might appear in the policy module:

'Insert a common name into the certificate

Dim CertPolicy As CCertServerPolicy
Set CertPolicy = New CCertServerPolicy

CertPolicy.SetCertificateProperty Context, _
Subject.CommonName, _
VT_STRING, _
"John Smith"

'Restrict key usage to digital signature only (KeyUsage=0)

CertPolicy.SetCertificateExtension Context, _
Extension.KeyUsage, _
VT_LONG, _
0

As can be seen from these examples, each method takes four inputs:

  1. A reference to the request being processed
  2. The property or extension which is being modified
  3. The data type of the property or extension
  4. The value.


Referencing Properties or Extensions

Every property or extension in a certificate includes an identifier called an Object ID (OID). Microsoft® Certificate Server interfaces can always reference a property or extension by referencing its OID. However, to make the process of specifying extensions via the policy module more intuitive, certain extensions are allowed to be referenced by name instead of requiring an Object ID. The list of supported named extensions includes many of the most commonly used extensions from the IETF, NIST, S/MIME and SET specifications. In addition, Microsoft CryptoAPI 2.0 supports a set of named properties and extensions which is more comprehensive. (See wincrypt.h in the CryptoAPI 2.0 for a complete listing.) These are available to extension handler routines.


Data Types Supported by Policy Modules

The third argument of the SetCertificateProperty and SetCertificateExtension methods is a constant representing the data type of the property or extension. Four data types are supported – String (VT_STRING), Long (VT_LONG), Time (VT_DATE), and Binary (VT_BINARY). String is used to specify a string value which is to be encoded as a Unicode string. Long is used to specify an integer value. Time is used to specify a ChoiceOfTime value. Binary is used to specify any type of data not covered by the other three types. This includes complex or custom certificate extensions which are encoded using extension handlers.


Writing Policy Modules in Visual Basic

To build a policy module in Microsoft® Visual Basic® version 5.0, build a class module called CertificateAuthority.Policy. This naming convention must be followed in order for RegSvr32 to store the GUID in the correct location in the system registry when it is run on the policy module DLL. To be sure of this, complete the following steps:

  1. Tools.Options.Project.ProjectName must be set to CertificateAuthority.
  2. Tools.Options.Project.Startup Form must be set to Sub Main.
  3. Tools.Options.Project.StartMode must be set to OLE Server.
  4. You must have a creatable class module named Policy. To create the module you must insert a class module, select View.Properties and edit all three fields: set Name to Policy, set Public to True and set Instancing to 2 (Creatable MultiUse.)
  5. Check the Tools.Options.Project.Advanced.OLE DLL.Use OLE DLL Restrictions check box
  6. If you call the Set/Get Property routines, you must run RegSvr32 Certif.dll prior to compiling the Visual Basic module, and you must also find Certif.dll in the Tools.References list box and make sure Certif.dll's "Certif 1.0 Type Library" check box is checked.
  7. Then use File.Make OLE DLL File to build the DLL.

The Class Module must have one method, named VerifyRequest. The VerifyRequest method will receive a request from the server and authorize or deny the request.

Note VerifyRequest is free to spawn off other processes or access an external database to do the request verification. If the verification requires out-of-band processing or human intervention, VerifyRequest can notify another process or leave any notice of the incoming request required. After the out-of-band processing is complete, a call to the Administration API can be made, or the provided administration utility can be used to resubmit the request to the policy module. The policy module can examine the request again, access any necessary external data and return a value to indicate the certificate should be issued or denied.


Visual Basic Policy Module Sample Code

The following sample code shows how to write a simple policy module in Microsoft® Visual Basic® that accepts requests only if the Subject.CommonName field is equal to "YourName".

Private const VR_INSTANT_OK as Long = 1
Private const VR_INSTANT_BAD as Long = 2
Public Function VerifyRequest( _
    strConfig as BSTR, _
    Context as Long, _
    bNewRequest as Long, _
    Flags as Long) as Integer

Dim Name as String
Dim CertPolicy As CCertServerPolicy
Set CertPolicy = New CCertServerPolicy
Name = CertPolicy.GetRequestProperty("Subject.CommonName", PROPTYPE_STRING)
If Name = "YourName" Then
    VerifyRequest = VR_INSTANT_OK
Else
    VerifyRequest = VR_INSTANT_BAD
End If
End Function


Policy Module Technical Notes

Policy modules should not provide a user interface because this will tie up the client thread (CertReq would seem to be deadlocked, for example). Also, by providing a user interface, the policy module must be able to interact with the Microsoft® Windows® desktop and run under the system account. This is only possible if Certificate Server is running as a stand-alone application in the diagnostics mode using the -z option. PolicyVB.dll does provide a user interface but is intended for demonstration purposes only.


Writing Exit Modules

Exit modules are COM objects that receive notifications from the Server Engine when operations such as the issuance of a certificate occur, and can call an interface that is a subset of the same interface called by the policy module. A typical operation for an exit module would be to publish a completed certificate in a specified location. Developers can refer to the source code for the default exit module to help write their own custom exit modules.


Default Exit Module

Microsoft® Certificate Server includes a default exit module, CertExit.dll. The source code for CertExit.dll can be modified to implement custom exit module functionality.

Note The default exit module in this release does not implement the ICertServerExit interface since it has no operations to perform. A future release of Certificate Server will include source code for a default exit module that implements the ICertServerExit interface and performs some operations.


Custom Exit Modules

Custom exit modules must implement the ICertExit interface, which is called by the Server Engine. The ICertExit::Initialize method is called by the Server Engine when the exit module is loaded. It allows the exit module to perform initialization and returns a value that informs the Server Engine of the kinds of events for which it wants notification. The ICertExit::GetDescription method must return a description string when the Server Engine requests it. The ICertExit::Notify method is called by the Server Engine to notify the exit module that an event has occurred.

Exit modules can call the ICertServerExit interface, which supports many of the same methods as the ICertServerPolicy interface, with the exception of the SetCertificateExtension and SetCertificateProperty methods.

See the Exit Module Customization topic in the Administrator's Guide for information on removing the existing exit module and installing a new one.

Note A future release of Certificate Server will support installation of multiple exit modules.


Writing Extension Handlers

The policy module interface for specifying certificate properties and extensions provides a simple means of controlling the information in a certificate using Microsoft® Visual Basic®. This interface allows the Visual Basic developer to avoid the complexities of ASN encoding but is limited to the default data types of BSTR, long and DATE. Support for more complex data types is included in the default extension handler, CertEnc.dll. CertEnc.dll is a COM object that is instantiated by the policy module and exports a number of ICertEncodeXXX interfaces. Developers who want to create custom extensions or need to encode a complex extension can write their own extension handlers that export custom interfaces.

Developers can refer to the source code provided for the ICertEncodeSampleStructure1 and ICertEncodeSampleStructure2 interfaces exported by CertEnc.dll as examples of interfaces for custom extension handlers. The sample structures provided demonstrate how to create a custom ASN structure that can be encoded and decoded by any callers of CryptEncodeObject and CryptDecodeObject in the CryptoAPI 2.0.

For more information about extension handlers, please see the following topics:

  • Default Extension Handler
  • Setting Certificate Extensions


Default Extension Handler

Microsoft® Certificate Server includes a default extension handler, CertEnc.dll, that provides routines for encoding the most commonly used extensions and data types such as IA5String, PrintableString, etc. These data types aren't among the default data types available from the policy module.

The non-default data types are supported by a number of ICertEncodeXXX interfaces exported by CertEnc.dll. Each interface provides an Encode method that returns an ASN encoded certificate extension to the policy module in a binary format. The policy module can then set the extension in a certificate by calling the ICertServerPolicy::SetCertificateExtension method. Here is an example written in Microsoft Visual Basic® that demonstrates how a policy module can encode a string array and use it to set a certificate extension:

Private Const szOID_TEST1 As String = "0.1.2.3.4.5.6.0"

Set StringArray = New CCertEncodeStringArray
Dim Extension As String

StringArray.Reset 3, CERT_RDN_IA5_STRING
StringArray.SetValue 0, "VB Test String 1"
StringArray.SetValue 1, "VB Test String 2"
StringArray.SetValue 2, "VB Test String 3"

Extension = StringArray.Encode

CertServer.SetCertificateExtension _
        szOID_TEST1, _
        PROPTYPE_BINARY, _
        EXTENSION_DISABLE_FLAG, _
        Extension


Setting Certificate Extensions

Extensions that have the default data types DATE, long, and BSTR can be set by the policy module without having to call the default extension handler or a custom handler. The policy module simply calls ICertServerPolicy::SetCertificateExtension with the Type parameter set to the corresponding property type of PROPTYPE_DATE, PROPTYPE_LONG, or PROPTYPE_STRING, and passes the extension to the Server Engine. The Server Engine then performs the ASN encoding before storing the extension in the certificate.

Extensions that have data types other than the default types must be ASN encoded by an extension handler before being passed by the policy module to the Server Engine. When the policy module calls ICertServerPolicy::SetCertificateExtension to pass an ASN encoded extension to the Server Engine, the Type parameter must be set to PROPTYPE_BINARY. The Server Engine then stores the pre-encoded extension in the certificate.


Writing Intermediaries

Intermediaries are programs written in Microsoft® C++®, Microsoft Visual Basic®, or Java that communicate with client applications to allow the submitting of certificate requests. Intermediaries can communicate with clients using any desired transport. Intermediaries must communicate with Certificate Server using the ICertRequest and ICertConfig interfaces provided by the Server Engine.


Appendixes

The following topics are discussed in these appendixes:

  • Certificate Request Property Names
  • Certificate Properties


Certificate Request Property Names

A certificate request Property Name can either be the "friendly" name of one of the common properties that the Certificate Server understands (see table following this paragraph) or an Object ID. If a Property Name refers to a "friendly" name not recognized by the Certificate Server, and it is prefixed with "RequestAttributes." or "Extension.", then the Request Attributes table or Certificate Extensions table will be used to lookup or set a site-specific property.

Valid Prefixes | Valid Suffixes | Equivalent Object ID Suffixes
Subject Issuer | Country Locality State StreetAddress Organization OrgUnit CommonName | 2.5.4.6 2.5.4.7 2.5.4.8 2.5.4.9 2.5.4.10 2.5.4.11 2.5.4.3
RawSubject |  |
RawIssuer |  |
Type |  |
Version |  |
RequestAttributes | <site-specific> |
Extension | IntendedUse |
PublicKey | Algorithm Modulus Exponent |
RawPublicKey |  |
NotBefore |  |
NotAfter |  |

Friendly Property Names can be specified by combining prefixes and suffixes from the preceding table. Suffixes can only be attached to prefixes in the same row. The following are some examples:

Prop1 = "Subject.CommonName"
Prop2 = "Issuer.CommonName"
Prop3 = "Issuer.2.5.4.3"     (2.5.4.3 is the Object ID for CommonName)
Prop4 = "Extension.1.3.4.2"    (1.3.4.2 is the Object ID of some unknown custom extension)


Certificate Properties

Microsoft® Certificate Server supports the use of certificates as defined in the ITU-T recommendation X.509 (also, ISO/IEC 9594-8). Other formats can be supported by extension handlers written for the formats. The following are properties that are contained in a standard X.509 certificate.

Field | Description
Version | Version number of the certificate.
Serial Number | Serial number of the certificate.
Algorithm Identifier | Signature algorithm used by the certificate signer.
Issuer Name | Name of the issuer of the certificate.
Validity | The time period over which the certificate is valid.
Not Before (Date) | Certificate not valid before this date.
Not After (Date) | Certificate not valid after this date.
Subject Name | Name of the person/entity to whom the certificate is being issued, including name, organization, organization unit, locality, state or province, and country.
Subject Public Key Info | Information about the subject's public key.
Algorithm | The algorithm used for the public key.
Subject Public Key | The actual public key (a bit string).
Optional Fields: | Optional fields
Issuer Unique ID | If present, version must be 2.0 or above.
Subject Unique ID | If present, version must be 2.0 or above.
Extensions | If present, version must be 3.0. For specifying any desired custom properties. Any number of extension fields can be included in the certificate.


About the Microsoft Certificate Enrollment Control

The Microsoft® Certificate Enrollment Control (CEC) is provided for corporate developers and independent software vendors (ISVs) who want to write custom modules and applications that must request a certificate be issued to the named user (subject). This guide documents the CEC's design and explains how to write applications incorporating it.

Portions of the following material assume that the reader has a basic familiarity with public-key cryptography, digital certificates, PKCS #7 and PKCS #10 standards, and how certificate stores are used in the Microsoft CryptoAPI. Readers who are new to these topics should read the PKCS standards that are available at http://www.rsa.com, and the CryptoAPI Programmers Guide and Reference, available in the Microsoft Platform SDK, before proceeding.


Certificate Enrollment Control Architecture

The CEC is designed to make it easier to develop an application that must request that a certificate be issued to a named subject. It is designed to accept data, in the form of a binary string (BSTR), from a web page, or from either a Microsoft® Visual Basic® or C++ user interface. The output from the CEC is a PKCS #10 certificate request, that can be sent on to a Certification Authority (CA) or a certificate server as shown in the following illustration.

Necessary information about the user (certificate subject) is collected by the User Interface (application), and is provided as a BSTR input to the CEC. The CEC generates the appropriate (signature or key exchange) key pair, and then generates and signs a PKCS #10 certificate request, using the generated private key. The CEC then stores the keys with the certificate request for later use. Next, the application sends the PKCS #10 to a certificate server or certification authority.

When the requested certificate is returned from the certificate server, the application passes the PKCS #7 message back to the CEC, where the certificate (or chain of certificates) is pulled from the PKCS #7 message. The user's public key (previously stored with the certificate request) is added to the newly received certificate, and the certificate is stored in a certificate store, as are any other certificates in the chain of trust. Any certificate-aware application can now access this certificate from the store.


Using the Microsoft Certificate Enrollment Control API

The CEC is a single object with many properties and several methods that can be used to determine how the CEC processes the user information, the type of certificate to be requested, how the keys are to be generated, where the certificate is to be stored, and so forth. There are two primary uses of the CEC: to create a certificate request (PKCS #10), and to receive the returned certificate and store it in a certificate store. For details and syntax for setting CEC properties and using CEC methods, see Certificate Enrollment Control API Overview


Creating the Certificate Request

The process of creating a certificate request involves collecting certain information from the requester. Usually, this is done through some sort of user interface (UI), although it could conceivably be taken directly from a database without the need for a UI. The required information is set by the policy of the certifying authority (CA). An example of the required information might be as follows:

Common Name
Unit Name
Company Name
City
State
Country

The following code is a simple example of how to use Visual Basic Script and HTML in a Web page to generate input for the CEC, and then to request a certificate. This example uses the default property values of the CEC object, and expects to find the xenroll.dll in the same directory.

<HTML>
<HEAD>
<TITLE>Enrollment HTML Page</TITLE>

<OBJECT
    classid="clsid:43F8F289-7A20-11D0-8F06-00C04FC295E1"
    CODEBASE="xenroll.dll"
    id=Enroll
    >
</OBJECT>

<SCRIPT LANGUAGE="VBSCRIPT">

    sub CertRequestSub

    '-----------------------------------------------------------------
    ' Create the data string.
    '-----------------------------------------------------------------
    DNName = "CN="  & document.CertRequest.CN.value & _
         ",OU=" & document.CertRequest.OU.value & _
         ",O="  & document.CertRequest.O.value  & _
         ",L="  & document.CertRequest.L.value  & _
         ",S="  & document.CertRequest.S.value  & _
         ",C="  & document.CertRequest.C.value

    '-----------------------------------------------------------------
    ' Create the PKCS10 message and put the keys in HKEY_CURRENT_USER
    ' on Local Machine.
    '-----------------------------------------------------------------

    document.data.Request.value = _
    Enroll.CreatePKCS10(DNName, "1.3.6.1.4.1.311.2.1.21")

    '-----------------------------------------------------------------
    ' Request the certificate.
    '-----------------------------------------------------------------

    document.data.submit()

    end sub

</SCRIPT>

</HEAD>
<BODY>

<FORM NAME="data" ACTION="scripts/certhtm.dll" METHOD=POST>
    <INPUT TYPE="HIDDEN" NAME="Request">
    <INPUT TYPE="HIDDEN" NAME="Server" VALUE="keithv2\Your Name">
</FORM>

<CENTER>
<BR><BR><BR><FONT SIZE=5 COLOR=Maroon><I><B>
Certificate Enrollment
</B></I></FONT>
<HR COLOR=Maroon WIDTH=75%>
<FORM NAME="CertRequest">
<TABLE>
<CAPTION ALIGN=LEFT VALIGN=TOP> Please Enter: </CAPTION>
<!-- Collect the data. -->
<TR><TD>Your Common Name:<TD><INPUT TYPE="TEXT" SIZE=32 NAME="CN">
<TR><TD>Your Unit Name:<TD><INPUT TYPE="TEXT" SIZE=32 NAME="OU">
<TR><TD>Your Company Name:<TD><INPUT TYPE="TEXT" SIZE=32 NAME="O">
<TR><TD>Your City:<TD><INPUT TYPE="TEXT" SIZE=32 NAME="L">
<TR><TD>Your State:<TD><INPUT TYPE="TEXT" SIZE=32 NAME="S">
<TR><TD>Your Country:<TD><INPUT TYPE="TEXT" SIZE=32 NAME="C">

<!-- Run the CertRequestSub subroutine. -->

<TR><TD ALIGN=center><INPUT TYPE="BUTTON" NAME="Request" value="Request Cert" onClick="CertRequestSub" language="VBScript">

<!-- Clear the input data. -->

<TD ALIGN=center><INPUT TYPE="RESET" NAME="Reset" value="Cancel">
</TABLE> <BR>
</FORM>

<HR COLOR=Maroon WIDTH=75%>
</CENTER>

</BODY>


Receiving the Returned Certificate

When the certifying authority has verified the information and is satisfied that the requester is the owner of the private key, and that the data about that requester is accurate, the CA constructs an x.509 certificate, signs it, packages it, along with any other needed certificates (such as the CA's own certificate) in a PKCS # 7 message, and sends the message to the requester.

The receiving application passes the PKCS # 7 message to the CEC. The CEC opens the message and extracts the certificates, putting any self-signed certificates in the "Root" store. The rest (except for the requester's certificate) are placed in the "CA" store. The CEC then adds the requester's public key to the requester's certificate, and places the requester's certificate in the certificate store specified by the requester in the MyStoreName property of the CEC.

The following code is a simple example of how to use Visual Basic Script and HTML in a Web page to receive and store the returned certificates, and to display the content of the requester's certificate:

<BODY>

<OBJECT
    classid="clsid:43F8F289-7A20-11D0-8F06-00C04FC295E1"
    CODEBASE="xenroll.dll"
    id=Enroll
    >
</OBJECT>

<OBJECT
    classid="clsid:41046D4F-AA27-11D0-8C5F-00C04FC29D45"
    CODEBASE="xformat.dll"
    id=Format
    >
</OBJECT>

'---------------------------------------------------------------------
' Name the form and data element.
'---------------------------------------------------------------------
<FORM NAME="result">
    <INPUT TYPE="HIDDEN" NAME="result">
</FORM>

<CENTER>
<SCRIPT LANGUAGE="VBSCRIPT">

    '-----------------------------------------------------------------
    'Accept the certificate sub-routine.
    '-----------------------------------------------------------------
    Sub AcceptCertSub

    On Error Resume Next

    Call Enroll.AcceptPKCS7(document.result.result.value)

    If err.Number = 0 Then
        navigate "..\done.htm"
    Else
        Alert "Error: " & Hex(err)
    End If

    End sub

    '-----------------------------------------------------------------
    ' Decline the certificate sub-routine.
    '-----------------------------------------------------------------
    Sub NoAcceptCertSub
    navigate "..\notdone.htm"
    End sub

    On Error Resume Next

    '--------------------------------------------------------------
    ' Get the issued certificate and display some of its parameters.
    ' The following value, "PKCS7", represents the received message.
    ' Actually, this value must be supplied through the design of
    ' the receiving application.
    ' -------------------------------------------------------------
    document.result.result.value = "PKCS7"

    X509Cert = Enroll.getCertFromPKCS7(document.result.result.value)

    If err.Number = 0 Then
        Call Format.init(X509Cert)
    End If

    ' &H20 is Issuer
    If err.Number = 0 Then
        szIssuer = Format.formatIssuer("COMMON NAME")
    End If

    ' &H40 is Subject
    If err.Number = 0 Then
        szSubject = Format.formatSubject("COMMON NAME")
    End If

    If err.Number = 0 Then
        szSerialNbr = Format.SerialNumber
    End If

    ' Not Before Date
    If err.Number = 0 Then
        szFrom    = Format.NotBefore
    End If

    ' Not After Date
    If err.Number = 0 Then
        szTo    = Format.NotAfter
    End If

    If err.Number = 0 Then

    '-----------------------------------------------------------------
    ' Display the data
    '-----------------------------------------------------------------
    document.write "<BR><BR><BR><BR>"
    document.write "<FONT COLOR=Maroon SIZE=5><CENTER>"
    document.write "<I><B>Certificate Acceptance</B></I>"
    document.write "<HR ALIGN=CENTER WIDTH=75% COLOR=Maroon>"
    document.write "<TABLE><TR><TD>Would you like to accept
        Certificate: <TD><I>"
    document.write szSubject
    document.write "</I><TR><TD>Issued by: <TD><I>"
    document.write szIssuer
    document.write "</I><TR><TD>Serial Number: <TD><I>"
    document.write szSerialNbr
    document.write "</I><TR><TD>Effective From: <TD><I>"
    document.write szFrom
    document.write "</I><TR><TD>Effective To: <TD><I>"
    document.write szTo
    document.write "</I><TR><TD ALIGN=center><INPUT TYPE=""BUTTON""
        NAME=""Accept"" value=""Accept"" onClick=""AcceptCertSub""
        language=""VBScript"">"
    document.write "<TD ALIGN=center><INPUT TYPE=""BUTTON""
        NAME=""No"" value=""No"" onClick=""NoAcceptCertSub""
        language=""VBScript"">"
    document.write "</TABLE></CENTER><FONT><BR>"
    document.write "<HR ALIGN=CENTER WIDTH=75% COLOR=Maroon>"

    End If

    If err.Number <> 0 Then
        Alert "Error: " & Hex(err)
    End If

</SCRIPT>

</CENTER>

</BODY>


Controlling the CEC

There are two ways to control the CEC: calling methods and setting properties.

There are methods that can perform the following tasks:

  • Create a PKCS #10 certificate request, either as a file or as an object in memory.
  • Receive certificates from a certificate server and store them in a certificate store or save them as a file.
  • Enumerate containers and providers.

For method details, see Certificate Enrollment Control Methods.

The methods use some properties to determine how to process the creation of a certificate request, and for processing a received certificate. For a detailed list of the properties, see Certificate Enrollment Control Properties.


Certificate Enrollment Control API Overview

The following sections provide information about the common attributes of the Microsoft® Certificate Enrollment Control (CEC) API.

The header file for the CEC methods and properties is xenroll.h.


Method Return Values

For each interface method there are two prototypes shown, each of which has the [VB] or [C++] notation beside it. The method prototypes return different values depending on which language is used.

Return Values For Microsoft Visual Basic

The return value is usually handled by a variant data structure that will automatically handle whatever type is returned. A method call would be as follows:

Dim HashAlgorithmValue As VARIANT  'return value

HashAlgorithmValue = get_HashAlgorithm( )

In this example code fragment, the return variable HashAlgorithmValue would be accepting a BSTR.

Return Values For Microsoft C++

The return value is always of type HRESULT, and it is from this return value that it can be determined whether or not the method or property call succeeded, and if not, what the error was. Programmatic values that need to be returned are returned through "output" parameters in the method. The following example shows a C++ method call to retrieve a request attribute:

ICEnroll*     iXenroll = NULL;
UINT          ucEnumProvIndex = 0;
BSTR          bstrProviders = NULL;
HRESULT       hr;

iXenroll = GetInterface();
hr       = iXenroll->enumProviders(ucEnumProvIndex, 0, &bstrProviders);

In the preceding code fragment, success or failure is returned to the "hr" variable.


Error Checking

In the case of Microsoft® Visual Basic®, if an error occurs within the method, the method will throw an exception. The script or program must check for these exceptions separately from the return value.

For C++, the return value is always an HRESULT, and indicates whether the method call succeeded or failed. If the call failed then the return value indicates why it failed.

Common HRESULT Values

The following table lists the values of common HRESULT values:

Name | Description
S_OK | Operation successful
ERROR_NO_MORE_ITEMS | An enumeration operation ran out of items.


IDispatch Support

The Microsoft® Certificate Enrollment Control interfaces include direct COM and IDispatch support. C++ applications should always use the direct COM interfaces.

To access Certificate Enrollment Control from Visual Basic Script include the following OBJECT element in your HTML document:

<OBJECT

classid="clsid:43F8F289-7A20-11D0-8F06-00C04FC295E1"
    CODEBASE="xenroll.dll"
    id=Enroll
    >
</OBJECT>


Certificate Enrollment Control Methods

The following methods are used by Certificate Enrollment Control and can be found in xenroll.dll:

Method | Description
acceptFilePKCS7 | This method accepts and processes a PKCS #7 (in BSTR form) containing a certificate. The BSTR is stored in a file.
acceptPKCS7 | This method accepts and processes a PKCS #7 (in BSTR form) containing a certificate. The PKCS #7 is input as a parameter.
createFilePKCS10 | This method creates a PKCS #10 (in BSTR form) that can be submitted to a certificate server, requesting that a certificate be issued to the person/entity whose information is supplied in the PKCS #10. The BSTR is saved to a file.
createPKCS10 | This method creates a PKCS #10 (in BSTR form) that can be submitted to a certificate server, requesting that a certificate be issued to the person/entity whose information is supplied in the PKCS #10.
enumContainers | This method enumerates all the containers for the provider specified in the ProviderName property. If that property has not been changed, then ProviderNames default value, as set in the registry, is used to do the enumeration.
enumProviders | This method enumerates all the providers available on the computer for the specified ProviderType property. If that property has not been changed, then the default value of the ProviderType, PROV_RSA_FULL, is used to do the enumeration.
freeRequestInfo | This method is used to clean up the stores if an error occurs or if the acceptance of a PKCS #7 is not to be performed for some reason. The BSTR (containing either PKCS #7 or #10 data) parameter specifies which previously persisted data gets cleaned up. It will clean up both the PKCS #7 and PKCS #10 data associated with the BSTR input. Currently not implemented.
getCertFromPKCS7 | This method is used to retrieve from a PKCS #7 just the single certificate that was issued in response to a PKCS #10. (The PKCS #7 may contain many certificates specifying the certification chain of authority that issued the certificate.)


acceptFilePKCS7

The acceptFilePKCS7 method accepts and processes a base64 encoded PKCS #7 (in BSTR form) containing a certificate. The BSTR is stored in a file.

The acceptFilePKCS7 method takes one parameter, a file containing the base64 encoded PKCS #7 (in BSTR form). It contains a certificate and the chain of certificates, possibly up to the root, identifying the issuer of the certificate. The certificate and the associated keys are put in the MY store. A root certificate is placed in the ROOT store and the rest of the chain of certificates are placed in the Certification Authority (CA) store. If any ROOT certificates are found in the PKCS #7, Crypt32 will notify the user that a ROOT is being added to his store. The user has the option of declining the ROOT certificate. This will not cause Certificate Enrollment Control to fail acceptance.

The only difference between this method and the acceptPKCS7 method is that the PKCS 7 to be processed is stored in a file for acceptFilePKCS7, where as acceptPKCS7 receives the PKCS 7 to be processed directly as a BSTR parameter.

[VB] void acceptFilePKCS7(
  BSTR wszPKCS10FileName
);

[C++] HRESULT acceptFilePKCS7 (
  BSTR wszPKCS10FileName    // in
);

Parameters

[VB][C++] wszPKCS10FileName
Specifies the name of the file where the BSTR containing the base64 encoded PKCS #7.

Return Values

acceptFilePKCS7 returns nothing. However, an error will be triggeredon failure.

Remarks

By default the system stores MY, CA, ROOT, and REQUEST are used for storing the certificates. However the stores to use may be specified by assigning the following properties before calling this method:

MyStoreName
CAStoreName
RootStoreName
RequestStoreName (a Certificate Enrollment defined system store)


acceptPKCS7

This method accepts and processes a base64 encoded PKCS #7 (in BSTR form) containing a certificate. The PKCS #7 is input as a parameter.

The acceptPKCS7 method takes one parameter, a base64 encoded PKCS #7 (in BSTR form) that contains a certificate and the chain of certificates, possibly up to the root, identifying the issuer of the certificate. The certificate and the associated keys generated for it are put in the MY store. A root certificate is placed in the ROOT store and the rest of the chain of certificates are placed in the Certification Authority (CA) store. If any ROOT certificates found in the PKCS #7 are accepted, Crypt32 will notify the user that a ROOT is being added to his store. The user has the option of declining the ROOT certificate. This will not cause Certificate Enrollment Control to fail acceptance.

By default the system stores MY, CA, ROOT, and REQUEST are used for storing the certificates. However the stores to use may be specified by assigning the following properties before calling this method:

MyStoreName
CAStoreName
RootStoreName
RequestStoreName (a Certificate Enrollment defined system store)

[VB] void acceptPKCS7(
  BSTR PKCS7
);

[C++] HRESULT acceptPKCS7 (
  BSTR PKCS7 // in
);

Parameters

[VB][C++] PKCS7
The base64 encoded PKCS #7 containing the certificate and the chain of certificates, possibly up to the root, identifying the issuer of the certificate.

Return Values

acceptPKCS7 returns nothing. However, an error will be thrown on failure.


createFilePKCS10

The createFilePKCS10 method creates a base64 encoded PKCS #10 (in BSTR form) that can be submitted to a certificate server, requesting that a certificate be issued to the person/entity whose information is supplied in the PKCS #10. The BSTR is saved to a file.

The createFilePKCS10 method has the same functionality as createPKCS10 with the additional feature of saving the base64 encoded PKCS #10 (in BSTR form) to the file specified by wszPKCS10FileName.

[VB] void createFilePKCS10(
  BSTR DNName,
  BSTR Usage,
  BSTR wszPKCS10FileName
);

[C++] HRESULT createFilePKCS10(
  BSTR DNName,            // in
  BSTR Usage,             // in
  BSTR wszPKCS10FileName  // in
);

Parameters

[VB][C++] DNName
The Distinguished Name (DN) name must follow the X500 naming convention. For example "CN=User, O=Microsoft". If a two-letter prefix does not exist, an object identifier (OID) may be provided instead.
[VB][C++] Usage
An OID that describes the purpose of the certificate being generated. For example, Individual or Commercial Authenticode certificate, or Client Auth.

The purpose OID is just passed through to the PKCS #10 request. For general extensibility and ease of understanding, the control does not attempt to understand specific purpose OIDs. Therefore if you specify a Client Auth OID, the generated keys will still be a signature key, not an exchange key.

[VB][C++] wszPKCS10FileName
When specified, designates a file in which the base64 encoded PKCS #10 (in BSTR form) is saved.

Return Values

The return value from createPKCS10 is a base64 encoded PKCS #10 request (in BSTR form). The format is such so that it can be directly posted to a WEB server for processing.

Remarks

By default, the Microsoft Base Cryptographic Provider is used, and unique a signature key is created.


createPKCS10

The createPKCS10 method creates a base64 encoded PKCS #10 (in BSTR form) that can be submitted to a certificate server, requesting that a certificate be issued to the person/entity whose information is supplied in the PKCS #10.

[VB] void createPKCS10(
  BSTR DNName,
  BSTR Usage
);

[C++] HRESULT createPKCS10(
  BSTR DNName,   // in
  BSTR Usage     // in
);

Parameters

[VB][C++] DNName
The DN name must follow the X500 naming convention. For example "CN=User, O=Microsoft". If a two-letter prefix does not exist, an OID may be provided instead.
[VB][C++] Usage
An OID that describes the purpose of the certificate being generated. For example, Individual or Commercial Authenticode certificate, or Client Authentication.

The purpose OID is just passed through to the PKCS #10 request. For general extensibility and ease of understanding, the control does not attempt to understand specific purpose OIDs. Therefore if you specify a Client Authentication OID, the generated key will still be a signature key, not an exchange key.

Return Values

The return value from createPKCS10 is a base64 encoded PKCS #10 request (in BSTR form). The format is such so that it can be directly posted to a Web server for processing.

Remarks

By default, the Microsoft Base Cryptographic Provider is used, PROV_RSA_FULL is the provider type, a signature key is created, and a unique new key set is created.


enumContainers

The enumContainers method enumerates all the containers for the provider specified in the ProviderName property. If that property has not been changed, then the default value of ProviderName (Microsoft Base Cryptographic Provider) as set in the registry, is used to do the enumeration.

[VB] BSTR enumContainers(
  DWORD dwIndex
);

[C++] HRESULT enumContainers (
  DWORD dwIndex,   // in
  BSTR *pbstr      // in
);

Parameters

[VB][C++] dwIndex
Specifying zero for dwIndex gets the first container. Increment dwIndex for successive containers. When there are no more containers, ERROR_NO_MORE_ITEMS is returned for [C++], and it is triggered for [VB].
[C++] pbstr
See "Return Value."

Return Values

Returns a BSTR containing the enumerated container. When there are no more containers, the error ERROR_NO_MORE_ITEMS is returned.


enumProviders

The enumProviders method enumerates all providers available on the computer for the specified ProviderType property. If that property has not been changed, then it has a default value of one, as set in the registry. This means PROV_RSA_FULL for the default Microsoft Base Cryptographic Provider is used to do the enumeration.

[VB] BSTR enumProviders(
  DWORD dwIndex,
  DWORD dwFlags
);

[C++] HRESULT enumProviders (
  DWORD dwIndex,         // in
  DWORD dwFlags,         // in
  BSTR *pbstrProvName    // in
);

Parameters

[VB][C++] dwIndex
Specifying zero for dwIndex gets the first provider. Increment dwIndex for successive providers. When there are no more providers, ERROR_NO_MORE_ITEMS is returned for [C++], and it is triggered for [VB].
VB][C++] dwFlags
These flags are passed through to CryptEnumProviders. See it for details.
[C++] pbstrProvName
See "Return Value."

Return Values

Returns a BSTR containing the enumerated provider. When there are no more providers, the error ERROR_NO_MORE_ITEMS is returned.


freeRequestInfo

The freeRequestInfo method is used to clean up the stores if an error occurs or if the acceptance of a PKCS #7 is not performed for some reason. The BSTR (containing either base64 encoded PKCS #7 or #10 data) parameter specifies which previously persisted store data will be cleaned up. Currently not implemented.

[VB] void freeRequestInfo(
  BSTR PKCS7OrPKCS10
);

[C++] HRESULT freeRequestInfo(
  BSTR PKCS7OrPKCS10    // in
);

Parameters

[VB][C++] PKCS7OrPKCS10
The BSTR (containing either base64 encoded PKCS #7 or #10 data) specifies which previously persisted store data gets cleaned up.

Return Values

Returns S_OK.


getCertFromPKCS7

The getCertFromPKCS7 method is used to retrieve from a PKCS #7 just the single certificate that was issued. (The PKCS #7 may contain many certificates specifying the certification chain of authority that issued the certificate.)

[VB] BSTR getCertFromPKCS7(
  BSTR wszPKCS7
);

[C++] HRESULT getCertFromPKCS7(
  BSTR wszPKCS7,      // in
  BSTR *pbstrCert     // in
);

Parameters

[VB][C++] wszPKCS7
Specifies the PKCS 7 from which the issued certificate is being retrieved.
[C++] pbstrCert
See "Return Value."

Return Values

Returns the single certificate (in BSTR form) that was issued.


Certificate Enrollment Control Properties

The setting of specific properties modifies the behavior of some methods. Each property is read/write, has an initialized default, and a set of acceptable values. A property may be set at anytime, but for them to have effect they should be set before calls to methods that use them.

Property | Description
CAStoreFlags | The CAStoreFlags are passed directly to CertOpenStore when the Certification Authority (CA) store is opened.
CAStoreName | The CAStoreName property specifies where all non-"ROOT" and non-"MY" certificates are kept.
CAStoreType | The CAStoreType property specifies the type of store to use for the store specified by the CAStoreName property.
ContainerName | The ContainerName property specifies the name of the key container to use.
DeleteRequestCert | The DeleteRequestCert property is used to control whether deletion occurs on a dummy certificate created for the purpose of persisting the keys generated for the PKCS #10 request for a certificate to be issued.
GenKeyFlags | The GenKeyFlags are passed directly to calls made to CryptGenKey.
HashAlgorithm | The HashAlgorithm refers only to the signature hash algorithm used to sign the PKCS #10.
KeySpec | The KeySpec is used to specify the key type to be generated.
MyStoreFlags | The MyStoreFlags are passed directly to CertOpenStore when the MY store is opened.
MyStoreName | The MyStoreName property specifies where certificates with linked private keys are kept.
MyStoreType | The MyStoreType property specifies the type of store to use for the store specified by the MyStoreName property.
ProviderFlags | The ProviderFlags property is dependent on the provider in use.
ProviderName | The ProviderName property specifies the cryptographic service provider (CSP) to use.
ProviderType | The ProviderType property is dependent on the provider in use.
PVKFileName | If the cryptographic service provider can support exporting of private keys, setting the PVKFileName property will attempt to generate the private keys as exportable and write the private key (as well as the public key) to the file specified by the PVKFileName property.
RequestStoreFlags | The RequestStoreFlags are passed directly to CertOpenStore when the REQUEST store is opened.
RequestStoreName | The RequestStoreName property specifies the certificate store used to store the dummy certificate to which the private keys have been added, until a certificate server processes the request and responds with a PKCS #7.
RequestStoreType | The RequestStoreType property specifies the type of store to use for the store specified by the RequestStoreName property.
RootStoreFlags | The RootStoreFlags are passed directly to CertOpenStore when the ROOT store is opened.
RootStoreName | The RootStoreName property specifies where all intrinsically trusted self-signed ROOT certificates are kept.
RootStoreType | The RootStoreType property specifies the type of store to use for the store specified by the RootStoreName property.
SPCFileName | The SPCFileName property specifies a file to write the resulting PKCS #7 (in BSTR form) as returned from the Certificate Server.
UseExistingKeySet | The UseExistingKeySet property must be set to TRUE if an existing key set is to be used instead of generating a new one.
WriteCertToCSP | The WriteCertToCSP property specifies whether a certificate can be written to the cryptographic service provider.


CAStoreFlags

The CAStoreFlags property value is passed directly to CertOpenStore when the Certification Authority (CA) store is opened. The default value for CAStoreFlags is CERT_SYSTEM_STORE_CURRENT_USER. Currently only CERT_SYSTEM_STORE_CURRENT_USER and CERT_SYSTEM_STORE_LOCAL_MACHINE are supported.

Data Type

[VB] DWORD
[C++] DWORD

Defined Values

CERT_SYSTEM_STORE_CURRENT_USER
CERT_SYSTEM_STORE_LOCAL_MACHINE

Affects the behavior of the following methods:

acceptPKCS7
acceptFilePKCS7

Access Methods

[VB] "="operator
[C++] HRESULT get_CAStoreFlags (DWORD);
HRESULT put_CAStoreFlags(DWORD);

HRESULT

Value | Meaning
S_OK | The property read/write completed successfully.


CAStoreName

The CAStoreName property specifies where all non-"ROOT" and non-"MY" certificates are kept. By default this is set to the "CA" system store.

Currently, only system store names can be specified.

Data Type

[VB] BSTR
[C++] BSTR

Defined Values

Any defined store name, such as:

"CA" (the default)
"MY"
"ROOT"

Affects the behavior of the following methods:

acceptPKCS7
acceptFilePKCS7

Access Methods

[VB] "="operator
[C++] HRESULT get_CAStoreName (BSTR);
HRESULT put_CAStoreName(BSTR);

HRESULT

Value | Meaning
S_OK | The property read/write completed successfully.


CAStoreType

The CAStoreType property specifies the type of store to use for the store specified by the CAStoreName property. CAStoreType's value is passed directly on to CertOpenStore. By default this value is sz_CERT_STORE_PROV_SYSTEM.

Currently only system stores are supported.

Data Type

[VB] BSTR
[C++] BSTR

Defined Values

The following store provider types are currently supported.

Store provider type | Value
sz_CERT_STORE_PROV_SYSTEM_W | "System"
sz_CERT_STORE_PROV_SYSTEM | "System"

Affects the behavior of the following methods:

acceptPKCS7
acceptFilePKCS7

Access Methods

[VB] "="operator
[C++] HRESULT get_CAStoreType (BSTR);
HRESULT put_CAStoreType(BSTR);

HRESULT

Value | Meaning
S_OK | The property read/write completed successfully.


ContainerName

The ContainerName property specifies the name of the key container to use. It may be an existing container or a new one. It may only be an existing container if the UseExistingKeySet property is set, as long as the key set has not been generated yet. For example, if only an exchange key set has been generated for a container, it is still possible to perform a certificate enrollment using the signature key set without setting UseExistingKeySet. The exchange key set could be used if UseExistingKeySet is set beforehand.

By default, a new container is selected each time the control is run. This ensures that a new key set is generated. Currently, a GUID is generated as the container name.

Data Type

[VB] BSTR
[C++] BSTR

Defined Values

Can be any specified name string from setting the property, or one will be automatically generated if the property has not been set.

Affects the behavior of the following methods:

createPKCS10
createFilePKCS10

Access Methods

[VB] "="operator
[C++] HRESULT get_ContainerName (BSTR);
HRESULT put_ContainerName(BSTR);

HRESULT

Value | Meaning
S_OK | The property read/write completed successfully.


DeleteRequestCert

The DeleteRequestCert property is used to control whether deletion occurs on a dummy certificate created for the purpose of persisting the keys generated for the PKCS #10 request for a certificate to be issued.

The store specified by the RequestStoreName property is where the dummy certificate is created. The newly generated keys are added as properties to the dummy certificate to persist them until a certificate server processes the request and responds with a PKCS 7. On acceptance of the PKCS #7, the dummy certificate is removed and the keys are added as properties of the issued certificate returned by the certificate server. For debugging and testing, it is often desirable to not delete the dummy certificate. Setting DeleteRequestCert to FALSE prevents its deletion. By default, this value is set to TRUE.

Data Type

[VB] BOOL
[C++] BOOL

Defined Values

TRUE (the default)
FALSE

Affects the behavior of the following methods:

acceptPKCS7
acceptFilePKCS7

Access Methods

[VB] "="operator
[C++] HRESULT get_DeleteRequestCert (BOOL);
HRESULT put_DeleteRequestCert (BOOL);

HRESULT

Value | Meaning
S_OK | The property read/write completed successfully.


GenKeyFlags

The GenKeyFlags property value is passed directly to calls made to CryptGenKey. By default it has a value of zero except when a .pvk file is specified using PVKFileName, where it defaults to a value of CRYPT_EXPORTABLE.

By default the private key is not exportable except when a .PVK file is requested. However, if the private key is to be exportable without a specified .pvk file, this flag should be set to CRYPT_EXPORTABLE. If the cryptographic service provider (CSP) does not support exportable private keys, an error occurs.

Data Type

[VB] DWORD
[C++] DWORD

Defined Values

The value for GenKeyFlags is passed through to CryptGenKey. For details, see CryptGenKey in the CryptoAPI documentation.

Affects the behavior of the following methods:

createPKCS10
createFilePKCS10

Access Methods

[VB] "="operator
[C++] HRESULT get_GenKeyFlags (DWORD);
HRESULT put_GenKeyFlags (DWORD);

HRESULT

Value | Meaning
S_OK | The property read/write completed successfully.


HashAlgorithm

The HashAlgorithm property refers only to the signature hash algorithm used to sign the PKCS #10. It is not to be confused with the hash algorithm used to sign the certificate. The enrollment control currently only supports SHA1 (the default), MD5, and MD2.

Data Type

[VB] BSTR
[C++] BSTR

Defined Values

"SHA1" (the default)
"MD2"
"MD5"

Affects the behavior of the following methods:

createPKCS10
createFilePKCS10

Access Methods

[VB] "="operator
[C++] HRESULT get_HashAlgorithm (BSTR);
HRESULT put_HashAlgorithm (BSTR);

HRESULT

Value | Meaning
S_OK | The property read/write completed successfully.


KeySpec

The KeySpec property is used to specify the key type to be generated. For the Microsoft® Base Cryptographic Provider, this will have a value of AT_KEYEXCHANGE for exchange keys, or AT_SIGNATURE for signature keys. However, this parameter is specific to the provider used and may be any value that makes sense to the provider. The default for Microsoft Base Cryptographic Provider is AT_SIGNATURE. For information on the other Microsoft® Cryptographic Service Providers, see Microsoft Cryptographic Service Providers in the CryptoAPI 2.0 documentation.

Data Type

[VB] DWORD
[C++] DWORD

Defined Values

Provider dependent. See your cryptographic service provider (CSP) for details.

Affects the behavior of the following methods:

createPKCS10
createFilePKCS10

Access Methods

[VB] "="operator
[C++] HRESULT get_KeySpec (DWORD);
HRESULT put_KeySpec (DWORD);

HRESULT

Value | Meaning
S_OK | The property read/write completed successfully.


MyStoreFlags

The MyStoreFlags property value is passed directly to CertOpenStore when the MY store is opened. The default value for MyStoreFlags is CERT_SYSTEM_STORE_CURRENT_USER. Currently only CERT_SYSTEM_STORE_CURRENT_USER and CERT_SYSTEM_STORE_LOCAL_MACHINE are supported.

Data Type

[VB] DWORD
[C++] DWORD

Defined Values

CERT_SYSTEM_STORE_CURRENT_USER
CERT_SYSTEM_STORE_LOCAL_MACHINE

Affects the behavior of the following methods:

acceptPKCS7
acceptFilePKCS7

Access Methods

[VB] "="operator
[C++] HRESULT get_MyStoreFlags (DWORD);
HRESULT put_MyStoreFlags (DWORD);

HRESULT

Value | Meaning
S_OK | The property read/write completed successfully.


MyStoreName

The MyStoreName property specifies where certificates with linked private keys are kept. The value of MyStoreName specifies the store in which to place the new certificate produced from acceptPKCS7 or acceptFilePKCS7. By default this is set to the "MY" system store.

Currently, only system store names can be specified.

Data Type

[VB] BSTR
[C++] BSTR

Defined Values

Any defined store name, such as:

"MY" (the default)
"CA"
"ROOT"

Affects the behavior of the following methods:

acceptPKCS7
acceptFilePKCS7

Access Methods

[VB] "="operator
[C++] HRESULT get_MyStoreName (BSTR);
HRESULT put_MyStoreName (BSTR);

HRESULT

Value | Meaning
S_OK | The property read/write completed successfully.


MyStoreType

The MyStoreType property specifies the type of store to use for the store specified by the MyStoreName property. The value for MyStoreType is passed directly on to CertOpenStore. By default this value is sz_CERT_STORE_PROV_SYSTEM.

Currently only system stores are supported.

Data Type

[VB] BSTR
[C++] BSTR

Defined Values

The following store provider types are currently supported.

Store provider type | Value
sz_CERT_STORE_PROV_SYSTEM_W | "System"
sz_CERT_STORE_PROV_SYSTEM | "System"

Affects the behavior of the following methods:

acceptPKCS7
acceptFilePKCS7

Access Methods

[VB] "="operator
[C++] HRESULT get_MyStoreType (BSTR);
HRESULT put_MyStoreType (BSTR);

HRESULT

Value | Meaning
S_OK | The property read/write completed successfully.


ProviderFlags

The ProviderFlags property is dependent on the provider in use. The value for ProviderFlags is passed directly though to calls to CryptAquireContext. By default this value is set to 0.

Data Type

[VB] DWORD
[C++] DWORD

Defined Values

For the default provider, Microsoft Base Cryptographic Provider, see CryptAcquireContext for details on the flags. For other providers, see them for details.

Affects the behavior of the following methods:

createPKCS10
createFilePKCS10

Access Methods

[VB] "="operator
[C++] HRESULT get_ProviderFlags (DWORD);
HRESULT put_ProviderFlags (DWORD);

HRESULT

Value | Meaning
S_OK | The property read/write completed successfully.


ProviderName

The ProviderName property specifies the cryptographic service provider (CSP) to use. If one has not been specified, the default is Microsoft Base Cryptographic Provider.

Data Type

[VB] BSTR
[C++] BSTR

Defined Values

Microsoft Base Cryptographic Provider (the default).

Affects the behavior of the following methods:

createPKCS10
createFilePKCS10
enumContainers

Access Methods

[VB] "="operator
[C++] HRESULT get_ProviderName (BSTR);
HRESULT put_ProviderName (BSTR);

HRESULT

Value | Meaning
S_OK | The property read/write completed successfully.


ProviderType

The ProviderType property is dependent on the provider in use. The value for ProviderType is passed directly through to calls to CryptAquireContext. It has a default value of one, as set in the registry. This means that PROV_RSA_FULL for the default Microsoft Base Cryptographic Provider is used to do the enumeration.

Data Type

[VB] DWORD
[C++] DWORD

Defined Values

See the documentation for the cryptographic service provider in use for defined values.

Affects the behavior of the following methods:

createPKCS10
createFilePKCS10
enumProviders

Access Methods

[VB] "="operator
[C++] HRESULT get_ProviderType (DWORD);
HRESULT put_ProviderType (DWORD);

HRESULT

Value | Meaning
S_OK | The property read/write completed successfully.


PVKFileName

Historically, Authenticode has exported the private key to a .pvk file on a disk and removed the keys from the registry. By default, private keys are not generated for exportation, and many cryptographic service providers do not support exporting keys. However, if the cryptographic service provider (CSP) can support exporting private keys, setting the PVKFileName property will attempt to generate the private keys as exportable. Setting the property will also write the private and public key to the file specified by the PVKFileName property. As a byproduct, the private key is removed from the CSP. The filename specified by the property can be any accessible file. By default, no .pvk file is generated and the keys are not generated as exportable.

If the .pvk file already exists, the user is notified and prompted for permission to overwrite.

Note The GenKeyFlags property also has a flag that controls whether the private key can be exported. Use care when utilizing the GenKeyFlags property and the PVKFileName property together. If the PVKFileName property is set first, the GenKeyFlags property is automatically set to CRYPT_EXPORTABLE. If the GenKeyFlags property is set (using the put_GenKeyFlags function) in this case without setting CRYPT_EXPORTABLE flag, then the GenKeyFlags will not be set to CRYPT_EXPORTABLE and the generated keys will not be exportable. The following example demonstrates this:

  1. Call put_PVKFileName to set the filename for the file that will receive the exported keys. The GenKeyFlags property is automatically set to CRYPT_EXPORTABLE.
  2. Call put_GenKeyFlags with a value not set to CRYPT_EXPORTABLE; for example, zero.
  3. GenKeyFlags is no longer set to CRYPT_EXPORTABLE (the value that was automatically set in step one).

Any keys generated following the previous steps will be not exportable. Therefore, it is recommended that the user set the GenKeyFlags property before the PVKFileName property when they are used together.

Alternatively, the user could determine the current value of the CRYPT_EXPORTABLE bit in the GenKeyFlags property, and then OR this value into any changes that are made to the GenKeyFlags property to ensure that the bit is not wiped out. The user could also specifically set the CRYPT_EXPORTABLE bit when updating the GenKeyFlags property.

Data Type

[VB] BSTR
[C++] BSTR

Defined Values

Any valid filename supported by the operating system in use.

Affects the behavior of the following methods:

createPKCS10
createFilePKCS10

Access Methods

[VB] "="operator
[C++] HRESULT get_PVKFileName (BSTR);
HRESULT put_PVKFileName (BSTR);

HRESULT

Value | Meaning
S_OK | The property read/write completed successfully.


RequestStoreFlags

The RequestStoreFlags property value is passed directly to CertOpenStore when the REQUEST store is opened. The default value for RequestStoreFlags is CERT_SYSTEM_STORE_CURRENT_USER. Currently only CERT_SYSTEM_STORE_CURRENT_USER and CERT_SYSTEM_STORE_LOCAL_MACHINE are supported. If the default is not used, this property must be set prior to making calls to createPKCS10 /createFilePKCS10 and again before calls to acceptPKCS7 /acceptFilePKCS7.

Typically, modification of the RequestStoreFlags property is only performed in advanced applications.

Data Type

[VB] DWORD
[C++] DWORD

Defined Values

CERT_SYSTEM_STORE_CURRENT_USER
CERT_SYSTEM_STORE_LOCAL_MACHINE

Affects the behavior of the following methods:

acceptPKCS7
acceptFilePKCS7
createPKCS10
createFilePKCS10

Access Methods

[VB] "="operator
[C++] HRESULT get_RequestStoreFlags (DWORD);
HRESULT put_RequestStoreFlags (DWORD);

HRESULT

Value | Meaning
S_OK | The property read/write completed successfully.


RequestStoreName

The RequestStoreName property specifies whereto store the dummy certificate with the added private keys until a certificate server processes the request and responds with a PKCS #7. By default the "REQUEST" system store is used. If the default is not to be used, this property must be set to the store to be used before calls to createPKCS10 /createFilePKCS10 and again before calls to acceptPKCS7 /acceptFilePKCS7.

Currently, only system store names can be specified for this property.

Typically, modification of the RequestStoreName property is only performed in advanced applications.

Data Type

[VB] BSTR
[C++] BSTR

Defined Values

Any defined store name, such as:

"REQUEST" (the default)
"ROOT"
"CA"
"MY"

Affects the behavior of the following methods:

acceptPKCS7
acceptFilePKCS7
createPKCS10
createFilePKCS10

Access Methods

[VB] "="operator
[C++] HRESULT get_RequestStoreName (BSTR);
HRESULT put_RequestStoreName (BSTR);

HRESULT

Value | Meaning
S_OK | The property read/write completed successfully.


RequestStoreType

The RequestStoreType property specifies the type of store to use for the store specified by the RequestStoreName property. The value for RequestStoreType is passed directly on to CertOpenStore. By default RequestStoreType's value is sz_CERT_STORE_PROV_SYSTEM. If the default is not to be used, this property must be set to the same value before calls to createPKCS10 /createFilePKCS10 and again before calls to acceptPKCS7 /acceptFilePKCS7.

Currently only system stores are supported.

Typically, modification of the RequestStoreType property is only performed in advanced applications.

Data Type

[VB] BSTR
[C++] BSTR

Defined Values

The following store provider types are currently supported.

Store provider type | Value
sz_CERT_STORE_PROV_SYSTEM_W | "System"
sz_CERT_STORE_PROV_SYSTEM | "System"

Affects the behavior of the following methods:

acceptPKCS7
acceptFilePKCS7
createPKCS10
createFilePKCS10

Access Methods

[VB] "="operator
[C++] HRESULT get_RequestStoreType (BSTR);
HRESULT put_RequestStoreType (BSTR);

HRESULT

Value | Meaning
S_OK | The property read/write completed successfully.


RootStoreFlags

The RootStoreFlags property value is passed directly to CertOpenStore when the ROOT store is opened. The default value for RootStoreFlags is CERT_SYSTEM_STORE_CURRENT_USER. Currently only CERT_SYSTEM_STORE_CURRENT_USER and CERT_SYSTEM_STORE_LOCAL_MACHINE are supported.

Data Type

[VB] DWORD
[C++] DWORD

Defined Values

CERT_SYSTEM_STORE_CURRENT_USER
CERT_SYSTEM_STORE_LOCAL_MACHINE

Affects the behavior of the following methods:

acceptPKCS7
acceptFilePKCS7

Access Methods

[VB] "="operator
[C++] HRESULT get_RootStoreFlags (DWORD);
HRESULT put_RootStoreFlags (DWORD);

HRESULT

Value | Meaning
S_OK | The property read/write completed successfully.


RootStoreName

The RootStoreName property specifies where all intrinsically trusted self-signed ROOT certificates are kept. By default this is set to the "ROOT" system store.

Currently, only system store names can be specified.

Data Type

[VB] BSTR
[C++] BSTR

Defined Values

Any defined store name, such as:

"ROOT" (the default)
"CA"
"MY"

Affects the behavior of the following methods:

acceptPKCS7
acceptFilePKCS7

Access Methods

[VB] "="operator
[C++] HRESULT get_RootStoreName (BSTR);
HRESULT put_RootStoreName (BSTR);

HRESULT

Value | Meaning
S_OK | The property read/write completed successfully.


RootStoreType

The RootStoreType property specifies the type of store to use for the store specified by the RootStoreName property. The value for RootStoreType is passed directly on to CertOpenStore. By default this value is sz_CERT_STORE_PROV_SYSTEM.

Currently only system stores are supported.

Data Type

[VB] BSTR
[C++] BSTR

Defined Values

The following store provider types are currently supported.

Store provider type | Value
sz_CERT_STORE_PROV_SYSTEM_W | "System"
sz_CERT_STORE_PROV_SYSTEM | "System"

Affects the behavior of the following methods:

acceptPKCS7
acceptFilePKCS7

Access Methods

[VB] "="operator
[C++] HRESULT get_RootStoreType (BSTR);
HRESULT put_RootStoreType (BSTR);

HRESULT

Value | Meaning
S_OK | The property read/write completed successfully.


SPCFileName

The SPCFileName property specifies a file to write the resulting base64 encoded PKCS #7 (in BSTR form) as returned from the Certificate Server. The file is written as a binary PKCS #7. Specifying this file does not affect the acceptance of the certificates into any of the users stores.

If the file already exists, the user is notified, and prompted for permission to overwrite.

Data Type

[VB] BSTR
[C++] BSTR

Defined Values

Any valid filename supported by the operating system in use.

Affects the behavior of the following methods:

acceptPKCS7
acceptFilePKCS7

Access Methods

[VB] "="operator
[C++] HRESULT get_SPCFileName (BSTR);
HRESULT put_SPCFileName(BSTR);

HRESULT

Value | Meaning
S_OK | The property read/write completed successfully.


UseExistingKeySet

The UseExistingKeySet property must be set to TRUE if an existing key set is used instead of generating a new one. By default, this property value is FALSE.

Data Type

[VB] BOOL
[C++] BOOL

Defined Values

TRUE
FALSE (the default)

Affects the behavior of the following methods:

createPKCS10
createFilePKCS10

Access Methods

[VB] "="operator
[C++] HRESULT get_UseExistingKeySet (BOOL);
HRESULT put_UseExistingKeySet (BOOL);

HRESULT

Value | Meaning
S_OK | The property read/write completed successfully.


WriteCertToCSP

The WriteCertToCSP property specifies whether a certificate can be written to the cryptographic service provider (CSP). This is typically used with smart cards, where the certificate is written to the card in addition to being written to the "MY" store.

Data Type

[VB] BOOL
[C++] BOOL

Defined Values

TRUE
FALSE (the default)

Affects the behavior of the following methods:

acceptPKCS7
acceptFilePKCS7

Access Methods

[VB] "="operator
[C++] HRESULT get_WriteCertToCSP (BOOL);
HRESULT put_WriteCertToCSP (BOOL);

HRESULT

Value | Meaning
S_OK | The property read/write completed successfully.


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

Remedy: Insert the MSDN Library CD into the CD-ROM drive.