Come and Check our BETA Alpha version of Powershellcenter.net
Send me your comment to Powershell@powershellcenter.com

Synopsis

Create a filter that determines which objects to pass along a command pipeline depending upon properties of X.509 certificates held in, or mapped to, input objects.

This cmdlet is part of the Quest ActiveRoles Server product. Use Get-QARSProductInfo to view information about ActiveRoles Server.

Syntax

Where-QADCertificate [-Certificate] <X509CertificateUI> [-AllEnhancedKeyUsages <string[]>] [-AllKeyUsages {None | EncipherOnly | CrlSign | KeyCertSign | KeyAgreement | DataEncipherment | KeyEncipherment | NonRepudiation | DigitalSignature | DecipherOnly}] [-AnyEnhancedKeyUsage <string[]>] [-AnyKeyUsage {None | EncipherOnly | CrlSign | KeyCertSign | KeyAgreement | DataEncipherment | KeyEncipherment | NonRepudiation | DigitalSignature | DecipherOnly}] [-CertificateAuthority] [-Expired] [-FriendlyName <string[]>] [-HasPrivateKey] [-IssuedBy <string[]>] [-IssuedTo <string[]>] [-IssuerDN <string[]>] [-KeyAlgorithm <string[]>] [-KeyAlgorithmParameters <string[]>] [-PrivateKeyExportable] [-PrivateKeyProtected] [-PublicKey <string[]>] [-Revoked] [-SerialNumber <string[]>] [-SignatureAlgorithm <string[]>] [-SubjectDN <string[]>] [-SubjectKeyIdentifier <string[]>] [-Template <string[]>] [-Thumbprint <string[]>] [-Valid] [-Version <int[]>] [<CommonParameters>]

Where-QADCertificate [-DirObj] <IGenericDirectoryObject> [-AllEnhancedKeyUsages <string[]>] [-AllKeyUsages {None | EncipherOnly | CrlSign | KeyCertSign | KeyAgreement | DataEncipherment | KeyEncipherment | NonRepudiation | DigitalSignature | DecipherOnly}] [-AnyEnhancedKeyUsage <string[]>] [-AnyKeyUsage {None | EncipherOnly | CrlSign | KeyCertSign | KeyAgreement | DataEncipherment | KeyEncipherment | NonRepudiation | DigitalSignature | DecipherOnly}] [-CertificateAuthority] [-Expired] [-FriendlyName <string[]>] [-HasPrivateKey] [-IssuedBy <string[]>] [-IssuedTo <string[]>] [-IssuerDN <string[]>] [-KeyAlgorithm <string[]>] [-KeyAlgorithmParameters <string[]>] [-PrivateKeyExportable] [-PrivateKeyProtected] [-PublicKey <string[]>] [-Revoked] [-SerialNumber <string[]>] [-SignatureAlgorithm <string[]>] [-SubjectDN <string[]>] [-SubjectKeyIdentifier <string[]>] [-Template <string[]>] [-Thumbprint <string[]>] [-Valid] [-Version <int[]>] [<CommonParameters>]

Where-QADCertificate [-Store] <X509CertificateStoreUI> [-AllEnhancedKeyUsages <string[]>] [-AllKeyUsages {None | EncipherOnly | CrlSign | KeyCertSign | KeyAgreement | DataEncipherment | KeyEncipherment | NonRepudiation | DigitalSignature | DecipherOnly}] [-AnyEnhancedKeyUsage <string[]>] [-AnyKeyUsage {None | EncipherOnly | CrlSign | KeyCertSign | KeyAgreement | DataEncipherment | KeyEncipherment | NonRepudiation | DigitalSignature | DecipherOnly}] [-CertificateAuthority] [-Expired] [-FriendlyName <string[]>] [-HasPrivateKey] [-IssuedBy <string[]>] [-IssuedTo <string[]>] [-IssuerDN <string[]>] [-KeyAlgorithm <string[]>] [-KeyAlgorithmParameters <string[]>] [-PrivateKeyExportable] [-PrivateKeyProtected] [-PublicKey <string[]>] [-Revoked] [-SerialNumber <string[]>] [-SignatureAlgorithm <string[]>] [-SubjectDN <string[]>] [-SubjectKeyIdentifier <string[]>] [-Template <string[]>] [-Thumbprint <string[]>] [-Valid] [-Version <int[]>] [<CommonParameters>]

Detailed Description

This cmdlet selects objects from the set of objects passed to it, based on properties of X.509 certificates held in, or mapped to, input objects. When the cmdlet receives an object, it checks to see whether the object contains, or is associated with, an X.509 certificate that matches the filter conditions specified by cmdlet parameters. If such a certificate exists, and is held in, or mapped to, an input object, the object is returned; otherwise, the object is ignored (filtered out). An input object may represent a certificate store, an Active Directory object (for example, a user account), or a certificate. In case of a certificate store object, the cmdlet allows the object to pass if the certificate store contains a certificate that matches the filter conditions. In case of an Active Directory object, the cmdlet allows the object to pass if a certificate that matches the filter conditions is mapped to that object in Active Directory. In case of a certificate object, the cmdlet allows the object to pass if the certificate represented by that object matches the filter conditions.

Parameters

-AllEnhancedKeyUsages [<string[]>]

Use this parameter to specify the object identifiers (OIDs) that indicate the intended purposes of the public key contained in the certificate to match, in addition to or in place of the key usage setting. Parameter value can be one or more OIDs or OID friendly names separated by commas. A list of some enhanced key usage OIDs can be found in Microsoft's article "IX509ExtensionEnhancedKeyUsage Interface" at msdn.microsoft.com/en-us/library/aa378132.aspx

This parameter causes the cmdlet to take account of a certificate when filtering input objects if the intended purposes of the certificate's key match all of the OIDs specified.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-AllKeyUsages [<X509KeyUsageFlags>]

Use this parameter to specify the key usage purpose for the certificates you want the cmdlet to take account of when filtering input objects. Parameter value can be any member of the X509KeyUsageFlags enumeration, such as EncipherOnly or DigitalSignature. For a complete list of the enumeration members, see the "X509KeyUsageFlags Enumeration" article in Microsoft's .NET Framework Class Library at msdn.microsoft.com/en-us/library/system.security.cryptography.x509certificates.x509keyusageflags.aspx

You can supply multiple members as an attribute value, separating them by commas. In this case, the cmdlet takes account of a certificate if the certificate's key is intended for each of the purposes defined by the members you specified.

The following values are permitted for this object type.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-AnyEnhancedKeyUsage [<string[]>]

Use this parameter to specify the object identifiers (OIDs) that indicate the intended purposes of the public key contained in the certificate to match, in addition to or in place of the key usage setting. Parameter value can be one or more OIDs or OID friendly names separated by commas. A list of some enhanced key usage OIDs can be found in Microsoft's article "IX509ExtensionEnhancedKeyUsage Interface" at msdn.microsoft.com/en-us/library/aa378132.aspx

This parameter causes the cmdlet to take account of a certificate when filtering input objects if the intended purposes of the certificate's key match any of the OIDs specified.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-AnyKeyUsage [<X509KeyUsageFlags>]

Use this parameter to specify the key usage purpose for the certificates you want the cmdlet to take account of when filtering input objects. Parameter value can be any member of the X509KeyUsageFlags enumeration, such as EncipherOnly or DigitalSignature. For a complete list of the enumeration members, see the "X509KeyUsageFlags Enumeration" article in Microsoft's .NET Framework Class Library at msdn.microsoft.com/en-us/library/system.security.cryptography.x509certificates.x509keyusageflags.aspx

You can supply multiple members as an attribute value, separating them by commas. In this case, the cmdlet takes account of a certificate if the certificate's key is intended for any of the purposes defined by the members you specified.

The following values are permitted for this object type.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-Certificate [<X509CertificateUI>]

Use this parameter to supply the certificate objects representing the certificates to filter. This could be output objects of the Get-QADCertificate or Import-QADCertificate cmdlet (see examples). If the certificate represented by a given object matches the conditions specified by the cmdlet parameters, the object is allowed to pass; otherwise, the object is filtered out.

Required?   true
Position?   1
Default value?  
Accept pipeline input?   true (ByValue)
Accept wildcard characters?   false

-CertificateAuthority [<SwitchParameter>]

Supply this parameter for the cmdlet to take account of only certification authority (CA) certificates. (CA certificates are certificates that are issued by a CA to itself or to a second CA for the purpose of creating a defined relationship between the two certification authorities.) If you want the cmdlet to take account of only the certificates that are not CA certificates, use the following syntax: -CertificateAuthority:$false.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-DirObj [<IGenericDirectoryObject>]

Use this parameter to supply the Active Directory objects, such as user accounts, to filter. This could be output objects of the Get-QADUser cmdlet (see examples). If a given Active Directory object is associated with a certificate that matches the conditions specified by the cmdlet parameters, the object is allowed to pass; otherwise, the object is filtered out.

Required?   true
Position?   1
Default value?  
Accept pipeline input?   true (ByValue)
Accept wildcard characters?   false

-Expired [<SwitchParameter>]

Supply this parameter for the cmdlet to take account of only expired certificates (a certificate is considered expired after the certificate's expiration date). If you want the cmdlet to take account of only the certificates that are not expired, use the following syntax: -Expired:$false.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-FriendlyName [<string[]>]

Use this parameter to specify the friendly name associated with the certificate to match. You can supply an array of strings each of which represents the friendly name of a single certificate, for the cmdlet to take account of the certificates that have any of the specified names.

Friendly name is an optional property of a certificate that can be set on an as-needed basis. It is possible to assign a friendly name to a certificate so the certificate can be easily identified.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   true

-HasPrivateKey [<SwitchParameter>]

Supply this parameter for the cmdlet to take account of only certificates containing a private key. With this parameter, the cmdlet takes account of a certificate only if the certificate has a private key associated with it. Without this parameter, the cmdlet does not consider the presence of a private key. If you want the cmdlet to take account of only the certificates that do not contain a private key, use the following syntax: -HasPrivateKey:$false.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-IssuedBy [<string[]>]

Use this parameter to specify the name of the certification authority (CA) that issued the certificate to match. You can supply an array of strings each of which represents the name of a single CA, for the cmdlet to take account of the certificates that were issued by any of the certification authorities specified.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-IssuedTo [<string[]>]

Use this parameter to specify the name of the principal to which the sought-for certificate was issued. You can supply an array of strings each of which represents a single principal's name, for the cmdlet to take account of the certificates that were issued to any of the principals specified.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-IssuerDN [<string[]>]

Use this parameter to specify the issuer distinguished name of the certificate to match. You can supply an array of strings each of which represents the distinguished name of a single certificate's issuer, for the cmdlet to take account of the certificates issued by any of the issuers specified.

The issuer distinguished name identifies the certification authority (CA) that issued the certificate. A distinguished name consists of name attributes, for example, "CN=Name,OU=OrgUnit,C=US".

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-KeyAlgorithm [<string[]>]

Use this parameter to specify the key algorithm information, in string format, for the certificate you want the cmdlet to take account of when filtering input objects. Parameter value is the object identifier (OID) or OID's friendly name that identifies the algorithm. You can specify an array of strings each of which identifies a certificate's key algorithm, for the cmdlet to take account of the certificates that use any of the specified key algorithms.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-KeyAlgorithmParameters [<string[]>]

Use this parameter to specify the hexadecimal string representing the key algorithm parameters of the certificate to match. You can supply an array of strings each of which represents the key algorithm parameters of a single certificate, for the cmdlet to take account of the certificates that have any of the specified key algorithm parameters.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-PrivateKeyExportable [<SwitchParameter>]

Supply this parameter for the cmdlet to take account of certificates containing an exportable private key. With this parameter, the cmdlet takes account of a certificate if the private key associated with the certificate can be exported. Without this parameter, the cmdlet does not consider whether the private key can be exported. If you want the cmdlet to take account of certificates whose private key cannot be exported, use the following syntax: -PrivateKeyExportable:$false.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-PrivateKeyProtected [<SwitchParameter>]

Supply this parameter for the cmdlet to take account of certificates containing a protected private key. With this parameter, the cmdlet takes account of a certificate if the private key associated with the certificate is protected. Without this parameter, the cmdlet does not consider whether the private key is protected. If you want the cmdlet to take account of certificates whose private key is not protected, use the following syntax: -PrivateKeyProtected:$false.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-PublicKey [<string[]>]

Use this parameter to specify the hexadecimal string representing the public key of the certificate to match. You can supply an array of strings each of which represents the public key associated with a single certificate, for the cmdlet to take account of the certificates that contain any of the keys specified.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-Revoked [<SwitchParameter>]

Supply this parameter for the cmdlet to take account of only revoked certificates. If you want the cmdlet to take account of only the certificates that are not revoked, use the following syntax: -Revoked:$false.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-SerialNumber [<string[]>]

Use this parameter to specify the serial number of the certificate to match. You can supply an array of strings each of which represents the serial number of a single certificate, for the cmdlet to take account of the certificates that have any of the specified serial numbers.

The serial number of a certificate is a unique number assigned to the certificate by the certification authority (CA) that issued the certificate.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-SignatureAlgorithm [<string[]>]

Use this parameter to specify the object identifier (OID) or OID's friendly name that identifies the type of the encryption algorithm used to create the signature of the certificate to match. You can supply an array of strings each of which identifies a single certificate's signature algorithm, for the cmdlet to take account of the certificates that use any of the algorithms specified.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-Store [<X509CertificateStoreUI>]

Use this parameter to supply the certificate store objects to filter. This could be output objects of the Get-QADLocalCertificateStore cmdlet (see examples). If the certificate store represented by a given object contains a certificate that matches the conditions specified by the cmdlet parameters, the object is allowed to pass; otherwise, the object is filtered out.

Required?   true
Position?   1
Default value?  
Accept pipeline input?   true (ByValue)
Accept wildcard characters?   false

-SubjectDN [<string[]>]

Use this parameter to specify the subject distinguished name of the certificate to match. You can supply an array of strings each of which represents the distinguished name of a single certificate's subject, for the cmdlet to take account of the certificates issued to any of the subjects specified.

The subject distinguished name is a textual representation of the certificate's subject. This representation consists of name attributes, for example, "CN=Name,OU=OrgUnit,C=US".

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-SubjectKeyIdentifier [<string[]>]

Use this parameter to specify the subject key identifier (SKI) of the certificate you want the cmdlet to take account of when filtering input objects. You can supply an array of strings each of which represents a single certificate's SKI encoded in hexadecimal format, for the cmdlet to take account of the certificates that have any of the specified subject key identifiers.

The subject key identifier can be used to differentiate between multiple public keys held by the certificate subject. The SKI value is typically an SHA-1 hash of the key.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-Template [<string[]>]

Use this parameter to specify the certificate template of the certificate to match. Parameter value is the name of a certificate template. You can supply an array of strings each of which represents the name of a certificate template, for the cmdlet to take account of the certificates that are based on any of the templates specified.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-Thumbprint [<string[]>]

Use this parameter to specify the thumbprint of the certificate to match. You can supply an array of strings each of which represents the thumbprint of a single certificate, for the cmdlet to take account of the certificates that have any of the specified thumbprints.

The thumbprint is a hash value generated using the SHA-1 algorithm that uniquely identifies the certificate. As such, the thumbprint of a certificate is commonly used to find the certificate in a certificate store.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-Valid [<SwitchParameter>]

Supply this parameter for the cmdlet to take account of only valid certificates. If you want the cmdlet to take account of only the certificates that are not valid, use the following syntax: -Valid:$false.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

-Version [<int[]>]

Parameter value is the X.509 format version of the certificates to match. For example, if you want the cmdlet to take account of only X.509 version 3 certificates, supply the parameter value of 3. An array of numbers causes the cmdlet to take account of certificates whose X.509 format version matches any of the numbers specified.

Required?   false
Position?   named
Default value?  
Accept pipeline input?   false
Accept wildcard characters?   false

Input Type

Quest.ActiveRoles.ArsPowerShellSnapIn.X509CertificateStorageUI, Quest.ActiveRoles.ArsPowerShellSnapIn.UI.GenericDirectoryObject, System.Security.Cryptography.X509Certificates.X509Certificate2

Return Type

Notes

Examples

EXAMPLE 1

PS> Get-QADLocalCertificateStore | Where-QADCertificate -Expired

Description

-----------

Retrieve all the certificate stores from the CurrentUser store location that contain any expired certificates. The output of this command is a set of objects each of which represents one of the certificate stores containing expired certificates.

EXAMPLE 2

PS> Get-QADUser | Where-QADCertificate -IssuerDN '*Microsoft*','*VeriSign*'

Description

-----------

Retrieve all user accounts from your Active Directory domain that are associated with certificates issued by Microsoft or VeriSign. The output of this command is a set of objects each of which represents one of the user accounts to which the sought-for certificates are mapped in Active Directory.

EXAMPLE 3

PS> $cert = dir c:\cert | Import-QADCertificate | Where-QADCertificate -Expired:$false C:\PS>Get-QADUser domainName\userName | Add-QADCertificate $cert

Description

-----------

Create a collection of objects ($cert) representing all the non-expired certificates found in the certificate files that are located in the specified folder (c:\cert). Then, pass those objects to the Add-QADCertificate cmdlet to map the corresponding certificates to the specified user account in Active Directory.

EXAMPLE 4

PS> Get-QADUser | Where-QADCertificate -AllKeyUsages None

Description

-----------

Retrieve users whose certificates in Active Directory have no key usage purpose specified.

EXAMPLE 5

PS> Get-QADUser | Where-QADCertificate -AllEnhancedKeyUsages ''

Description

-----------

Retrieve users whose certificates in Active Directory have no key intended purpose specified.