DistributionPoint (6.0 API Documentation)

java.lang.Object
- iaik.asn1.structures.DistributionPoint

```
public class DistributionPoint
extends java.lang.Object
```
This class implements the ASN.1 type DistributionPoint as used within a CRLDistributionPoints or FreshestCRL X.509v3 extension for identifying how CRL information is obtained.
The X.509 Certificate and CRL profile presented in RFC 3280 specifies a DistributionPoint as ASN.1 SEQUENCE structure which may contain a distribution point name that typically may be a URI pointing to the current CRL for the associated reasons, issued by the associated cRLIssuer:
```
 DistributionPoint ::= SEQUENCE {
    distributionPoint       [0]     DistributionPointName OPTIONAL,
    reasons                 [1]     ReasonFlags OPTIONAL,
    cRLIssuer               [2]     GeneralNames OPTIONAL }
 

 DistributionPointName ::= CHOICE {
    fullName                [0]     GeneralNames,
    nameRelativeToCRLIssuer [1]     RelativeDistinguishedName }
 

 ReasonFlags ::= BIT STRING {
    unused                  (0),
    keyCompromise           (1),
    cACompromise            (2),
    affiliationChanged      (3),
    superseded              (4),
    cessationOfOperation    (5),
    certificateHold         (6),
    privilegeWithdrawn      (7),
    aACompromise            (8) }
 
```
If the distributionPoint omits reasons, the referenced CRL shall include revocations for all reasons. If the distributionPoint omits cRLIssuer, the referenced CRL has to be issued by the CA that issued the certificate, otherwise the referenced CRL is an indirect CRL and the crlIssuer field has to be present.
The DistributionPointName maybe a GeneralNames object (fullName field) or a RelativeDistinguishedName (nameRelativeToCRLIssuer field).
If given as GeneralNames, the distribution name typically will represent a URI pointing to a location from where the CRL can be obtained. If the GeneralNames contains more than one value, each value uses a different mechanism to reference the same CRL (for instance, one value may represent a http url and a second value may represent an ldap url from where the same crl can be loaded).
If the distribution point name is given as RelativeDistinguishedName, the RDN value has to be appended to the distinguished name of the CRL issuer to represent an entry in a X.500 or LDAP directory. If the cRLIssuer field is present (indirect CRL), it has to contain a distinguished name to which the distribution point name RDN has to be appended. Otherwise (if the cRLIssuer field is not set) the crl issuer is the same as the certificate issuer and the distribution point name RDN has to be appended to the distinguished name of the certificate issuer.
If the DistributionPointName field is not present, the cRLIssuer field must be present and must represent the DN of a X.500 or LDAP directory from which the crl can be obtained.
More information can be found in the X.509 Certificate and CRL profile presented in RFC 3280, section 4.2.1.14 "CRLDistributionPoints".
When creating a DistributionPoint object to be used for the CRLDistributionPoints extension, you may supply the distributionPointName immediately, and subsequently use the setReasonFlags and/or setCrlIssuer methods for setting the reasons and/or cRLIssuer fields, e.g.:
```
 String crlUri = "http://ca.iaik.at/test.crl";
 DistributionPoint dp = new DistributionPoint(new String[] { crlUri });
 dp.setReasonFlags(DistributionPoint.keyCompromise);
 // assume indirect crl where crl issuer is not certificate issuer
 X509Certificate crlIssuerCert = ...;
 dp.setCrlIssuerName(crlIssuerCert.getSubjectDN()); 
 // create CRLDistributionPoints extension
 CRLDistributionPoints cRLDistributionPoints = new CRLDistributionPoints(dp); 
 // add extension to certificate
 X509Certificate cert = ...;
 ...
 cert.addExtension(cRLDistributionPoints);
 ...
 
```
On the receiving side, when validating a CRLDistributionPoints or FreshestCRL extension of a certificate, you may check the included DistributionPoints:
```
 X509Certificate cert = ...;
 ...
 // get CRLDistributionPoints extension
 CRLDistributionPoints cRLDistributionPoints = cert.getExtension(CRLDistributionPoints.oid);
 if (cRLDistributionPoints != null) {
   // get DistributionPoints
   Enumeration e = cRLDistributionPoints.getDistributionPoints();
   while (e.hasMoreElements()) {
     DistributionPoint dp = (DistributionPoint)e.nextElement();
     // assume URI distribution point name(s)
     String[] crlUris = dp.getDistributionPointNameURIs();
     ...
     // get CRL issuer
     Name crlIssuerName = dp.getCrlIssuerName();
     if (crlIssuerName != null) {
       ...
     }
     // get reason flags
     int reasonFlags = dp.getReasonFlags();
     if (reasonFlags != -1) {
       ...
     }
   }
 }
 
 
```
While stepping through the DistributionPoints contained in a CRLDistributionPoints or FreshestCRL extension you may use method loadCrl or loadCrl(String ldapUrl, Name crlIssuer) for downloading the crl from its distribution point.
Most usually you only will need the first method (loadCrl) since it downloads the crl from an uri distribution point name which is the most common way of referencing a crl location from within a DistributionPoint. If more than one distribution point name value is present, each value uses a different mechanism to point to the same CRL. For instance, a DistributionPointName may contain two uri values, one pointing to a "http" location (e.g. "http://democa.iaik.at/testCA.crl") and the second pointing to a "ldap" location (e.g. "ldap://demoldap.iaik.at/cn=TestCA,o=iaik,c=at?certificateRevocationList;binary"). Method loadCrl steps through all uri distribution point names included and tries to download the crl from them. In the sample above, loadCrl first would connect to "http://democa.iaik.at/testCA.crl" and try to download the crl from it. If not successful the second (and in this example last) distribution point name "ldap://demoldap.iaik.at/cn=TestCA,o=iaik,c=at?certificateRevocationList;binary" is contacted to download the crl from it.
If you want to be sure that this DistributionPoint contains an distribution point name of type uniformResourceIdentifier, you first may call method containsUriDpName:
```
 ...
   DistributionPoint dp = (DistributionPoint)e.nextElement();
   if (dp.containsUriDpName()) {
     // download crl
     X509CRL crl = dp.loadCrl();
     ...
   }
 ...  
 
```
If you expect to download a very large crl you alternatively may call method loadCrlStream and use the stream based crl implementation of IAIK-JCE for parsing the crl.
If this distribution point does not contain a uri distribution point name, but a RDN and/or cRLIssuer field, you may use method loadCrl(String url, Name certificateIssuer) for downloading the crl from a specific entry of an ldap server. In this case the DistributionPoint only contains the DN pointing to an entry at the ldap directory, but does not contain the ldap server url itself. For that reason you have to specify the ldap server url when calling method loadCrlStream, e.g.:
```
 String url = "ldap://demoldap.iaik.at";
 Name crlIssuer = ...;
 DistributionPoint distributionPoint = ...;
 X509CRL crl = distributionPoint.loadCrl(url, crlIssuer);
 
```
The crlIssuer only has to be specified if the cRLIssuer field of the DistributionPoint is not set and therefore the crl issuer is the same entity as the certificate issuer. For instance, let us assume, that the distributionPoint from above is included in a CRLDistributionPoints extension and contains a RDN distribution point name with "cn=crl". The crlIssuer shall be given as "cn=TestCA,o=iaik,c=at". In this case the crl is downloaded from the entry "cn=crl,cn=TestCA,o=iaik,c=at" from the ldap server running at "ldap://demoldap.iaik.at".
If you expect to download a large crl you alternatively may call method loadCrlStream(String ldapUrl, Name certificateIssuer) and use the stream based crl implementation of IAIK-JCE for parsing the crl.
All loadCrl, loadCrlStream methods use an java.net.URLConnection for downloading the crl. Thus only protocols can be supported for which an java.net.URLStreamHandler is available. Since the http protocol is supported by the JDK by default, crls can be downloaded from http uri distribution point names. If you want to support ldap, too, you will have to register the IAIK LdapURLConnection implementation, e.g. by using the java.protocol.handler.pkgs system property:
```
 System.getProperties().put("java.protocol.handler.pkgs", "iaik.x509.net");
 
```
In this case you will have to ensure that the Java Naming and Directory interface (JNDI) is available. For JDK versions >=1.3 the JNDI is included in the JDK, for JDK versions <1.3 you also will have to put jndi.jar, ldap.jar and providerutil.jar into your classpath which can be downloaded from the JNDI homepage at SUN: http://java.sun.com/products/jndi.
Version:

File Revision 39

See Also:
CRLDistributionPoints, FreshestCRL, GeneralNames, GeneralName, Name, X509Certificate, X509CRL, LdapURLConnection

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`aACompromise` The `aACompromise` reason flag.
`static int`	`affiliationChanged` The `affiliationChanged` reason flag.
`static int`	`cACompromise` The `cACompromise` reason flag.
`static int`	`certificateHold` The `certificateHold` reason flag.
`static int`	`cessationOfOperation` The `cessationOfOperation` reason flag.
`static int`	`keyCompromise` The `keyCompromise` reason flag.
`static int`	`privilegeWithdrawn` The `privilegeWithdrawn` reason flag.
`static int`	`superseded` The `superseded` reason flag.
`static int`	`unused` The `unused` reason flag.

Constructor Summary

Constructors
Constructor and Description
`DistributionPoint()` Default constructor.
`DistributionPoint(ASN1Object distributionPoint)` Constructs a DistributionPoint from an ASN1Object.
`DistributionPoint(ASN1Type distributionPointName)` Creates a new DistributionPoint for the given distribution point name, specified as `RDN` or a `GeneralNames`.
`DistributionPoint(java.lang.String[] uriNames)` Creates a new DistributionPoint with the given URI strings as distribution point name values.

Method Summary

Methods
Modifier and Type	Method and Description
`boolean`	`containsUriDpName()` Checks if this DistributionPoint contains any uri distribution point name.
`GeneralNames`	`getCrlIssuer()` Returns the CRL Issuer parameter of this distribution point, if set.
`Name`	`getCrlIssuerName()` Returns the CRL Issuer name of this distribution point, if set.
`ASN1Type`	`getDistributionPointName()` Returns the distribution point name of this distribution point.
`java.lang.String[]`	`getDistributionPointNameURIs()` Returns all distribution point name values of type `uniformResourceIdentifier` that are included in this DistributionPoint.
`java.lang.String[]`	`getDistributionPointNameURIs(java.lang.String protocol)` Returns all distribution point name values of type `uniformResourceIdentifier` of the given protocol that are included in this DistributionPoint.
`int`	`getReasonFlags()` Returns the reason flags specification of this distribution point.
`boolean`	`isSet(int reasonFlags)` Checks whether the specified reasonFlags values are set.
`X509CRL`	`loadCrl()` Downloads the crl from an uri distribution point name (if this DistributionPoint contains an uri distribution point name).
`X509CRL`	`loadCrl(java.lang.String ldapUrl, Name crlIssuer)` Downloads the crl from the given ldap server url (if this DistributionPoint contains a RelativeDistinguished RDN distribution point name, or the distribution point name is not present but the cRLIssuer field is set).
`java.io.InputStream`	`loadCrlStream()` Connects to and downloads the crl from an uri distribution point name (if this DistributionPoint contains an uri distribution point name) and provides a input stream from where the crl can be read.
`java.io.InputStream`	`loadCrlStream(java.lang.String ldapUrl, Name crlIssuer)` Connects to and downloads the crl from the given ldap server url (if this DistributionPoint contains a RelativeDistinguished RDN distribution point name, or the distribution point name is not present but the cRLIssuer field is set).
`void`	`setCrlIssuer(GeneralNames crlIssuer)` Sets the CRL Issuer parameter of this DistributionPoint.
`void`	`setCrlIssuerName(Name crlIssuerName)` Sets the CRL Issuer parameter to the given crl issuer name.
`void`	`setCrlIssuerName(X509Certificate crlIssuerCert)` Sets the CRL Issuer parameter from the given crl issuer certificate.
`void`	`setDistributionPointName(ASN1Type distributionPointName)` Sets the distribution point name parameter of this extension.
`void`	`setDistributionPointNameURIs(java.lang.String[] uriNames)` Sets distribution point name values of type `uniformResourceIdentifier` that shall be included in this DistributionPoint.
`void`	`setLdapAttributeDescription(java.lang.String attributeDescription)` Sets the attribute description to be used when downloading a crl from an ldap server.
`void`	`setReasonFlags(int reasonFlags)` Sets the reason flags parameter of this extension.
`ASN1Object`	`toASN1Object()` Returns this DistributionPoint as (SEQUENCE) ASN1Object.
`java.lang.String`	`toString()` Returns a string that represents the contents of this DistributionPoint.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - unused
```
public static final int unused
```
    The unused reason flag.
    
    See Also:
    Constant Field Values
  - keyCompromise
```
public static final int keyCompromise
```
    The keyCompromise reason flag.
    
    See Also:
    Constant Field Values
  - cACompromise
```
public static final int cACompromise
```
    The cACompromise reason flag.
    
    See Also:
    Constant Field Values
  - affiliationChanged
```
public static final int affiliationChanged
```
    The affiliationChanged reason flag.
    
    See Also:
    Constant Field Values
  - superseded
```
public static final int superseded
```
    The superseded reason flag.
    
    See Also:
    Constant Field Values
  - cessationOfOperation
```
public static final int cessationOfOperation
```
    The cessationOfOperation reason flag.
    
    See Also:
    Constant Field Values
  - certificateHold
```
public static final int certificateHold
```
    The certificateHold reason flag.
    
    See Also:
    Constant Field Values
  - privilegeWithdrawn
```
public static final int privilegeWithdrawn
```
    The privilegeWithdrawn reason flag.
    
    See Also:
    Constant Field Values
  - aACompromise
```
public static final int aACompromise
```
    The aACompromise reason flag.
    
    See Also:
    Constant Field Values
- Constructor Detail
  - DistributionPoint
```
public DistributionPoint()
```
    Default constructor. Creates an empty DistributionPoint object.
    By default, reasonFlag is set to -1 indicating that no reason is selected, DistributionPointName and CrlIssuer are set to null. Use setReasonFlags, setDistributionPointName, setCrlIssuer for setting the corresponding values.
  - DistributionPoint
```
public DistributionPoint(ASN1Type distributionPointName)
                  throws java.lang.IllegalArgumentException
```
    Creates a new DistributionPoint for the given distribution point name, specified as RDN or a GeneralNames. The supplied distribution point name has to be a RDN or a GeneralNames object:
```
 
 DistributionPoint ::= SEQUENCE {
    distributionPoint       [0]     DistributionPointName OPTIONAL,
    reasons                 [1]     ReasonFlags OPTIONAL,
    cRLIssuer               [2]     GeneralNames OPTIONAL }

 DistributionPointName ::= CHOICE {
    fullName                [0]     GeneralNames,
    nameRelativeToCRLIssuer [1]     RelativeDistinguishedName }
 
```
    Most usually the fullName GeneralNames choice will be used with the GeneralName type uniformResourceIdentifier to specify a distribution point name that points to some location from where the crl can be obtained, e.g.:
```
 String uri = "http://democa.iaik.at/testCA.crl";
 GeneralName uriName = new GeneralName(GeneralName.uniformResourceIdentifier, uri);
 GeneralNames dpName = new GeneralNames(uriName); 
 DistributionPoint dp = new DistributionPoint(dpName);
 
```
    However, in this case it might be more convenient to use constructor DistributionPoint(String[]) where the URI distribution point name values can be immediately specified as String objects:
```
 String uri = "http://democa.iaik.at/testCA.crl";
 DistributionPoint dp = new DistributionPoint(new String[] { uri });
 
```
    If the distribution point name uses the nameRelativeToCRLIssuer choice the relative distinguished name (RDN) has to be appended to the X.500 distinguished name of the crl issuer to give the actual distribution point name (the crl issuer may be specified by the cRLIssuer field (i.e. indirect crl) or may be given by the issuer field of the certificate (in this case the certificate issuer is also the crl issuer)), for instance:
```
 RDN distributionPointName = new RDN();
 ...
 // add AVAs as required
 distributionPointName.addAVA(...);
 ...
 // create distribution point
 DistributionPoint distributionPoint = new DistributionPoint(distributionPointName);
 
```
    By default, reasonFlag is set to -1 indicating that no reason is selected.
    Parameters:
    distributionPointName - the name of the distribution point as RDN or GeneralNames object
    
    Throws:
    
    java.lang.IllegalArgumentException - if the given name is not an instance of RDN or GeneralNames
    See Also:
    GeneralName, RDN
  - DistributionPoint
```
public DistributionPoint(java.lang.String[] uriNames)
```
    Creates a new DistributionPoint with the given URI strings as distribution point name values.
    Distribution point names of type uniformResourceIdentifier are the most common types of distribution point names that may be included in a DistributionPoint. A distribution point name of type uniformResourceIdentifier points to a location from where the CRL can be obtained. If more than one distribution point name value is present, each value uses a different mechanism to point to the same CRL. For instance, a distribution point name may contain two uri values, one pointing to a "http" location (e.g. "http://democa.iaik.at/test.crl") and the second pointing to a "ldap" location (e.g. "ldap://demoldap.iaik.at/cn=TestCA,o=iaik,c=at?certificateRevocationList;binary"), e.g.:
```
 String httpUri = "http://democa.iaik.at/testCA.crl";
 String ldapUri = "ldap://demoldap.iaik.at/cn=TestCA,o=iaik,c=at?certificateRevocationList;binary";
 DistributionPoint dp = new DistributionPoint(new String[] { httpUri, ldapUri });
 
```
    Parameters:
    uriNames - a String array containing distribution point name values of type uniformResourceIdentifier to be set for this distribution point
  - DistributionPoint
```
public DistributionPoint(ASN1Object distributionPoint)
                  throws CodingException
```
    Constructs a DistributionPoint from an ASN1Object.
    The given distribution point ASN1Object is parsed for any distribution point name, reasons specification and CRLIssuer.
    
    Parameters:
    distributionPoint - the DistributionPoint as ASN1Object
    
    Throws:
    
    CodingException - if an error occurs when parsing the ASN.1 object
- Method Detail
  - toASN1Object
```
public ASN1Object toASN1Object()
                        throws CodingException
```
    Returns this DistributionPoint as (SEQUENCE) ASN1Object.
    The ASN1Object returned by this method will represent a SEQUENCE that may contain the DistributionPointName, ReasonFlags and cRLIssuer components:
```
 
 DistributionPoint ::= SEQUENCE {
    distributionPoint       [0]     DistributionPointName OPTIONAL,
    reasons                 [1]     ReasonFlags OPTIONAL,
    cRLIssuer               [2]     GeneralNames OPTIONAL }

 DistributionPointName ::= CHOICE {
    fullName                [0]     GeneralNames,
    nameRelativeToCRLIssuer [1]     RelativeDistinguishedName }
    
 ReasonFlags ::= BIT STRING {
    unused                  (0),
    keyCompromise           (1),
    cACompromise            (2),
    affiliationChanged      (3),
    superseded              (4),
    cessationOfOperation    (5),
    certificateHold         (6),
    privilegeWithdrawn      (7),
    aACompromise            (8) }   
 
```
    Returns:
    this DistributionPoint as ASN1Object
    
    Throws:
    
    CodingException - if there was an error while constructing the ASN1Object
  - setDistributionPointName
```
public void setDistributionPointName(ASN1Type distributionPointName)
                              throws java.lang.IllegalArgumentException
```
    Sets the distribution point name parameter of this extension.
    The supplied distribution point name has to be a RDN or a GeneralNames object:
```
 
 DistributionPoint ::= SEQUENCE {
    distributionPoint       [0]     DistributionPointName OPTIONAL,
    reasons                 [1]     ReasonFlags OPTIONAL,
    cRLIssuer               [2]     GeneralNames OPTIONAL }

 DistributionPointName ::= CHOICE {
    fullName                [0]     GeneralNames,
    nameRelativeToCRLIssuer [1]     RelativeDistinguishedName }
 
```
    Most usually the fullName GeneralNames choice will be used with the GeneralName type uniformResourceIdentifier to specify a distribution point name that points to some location from where the crl can be obtained, e.g.:
```
 String uri = "http://democa.iaik.at/testCA.crl";
 GeneralName uriName = new GeneralName(GeneralName.uniformResourceIdentifier, uri);
 GeneralNames dpName = new GeneralNames(uriName); 
 DistributionPoint dp = ...;
 dp.setDistributionPointName(dpName);
 
```
    However, in this case it might be more convenient to use method setDistributionPointNameURIs(String[]) where the URI distribution point name values can be immediately specified as String objects:
```
 String uri = "http://democa.iaik.at/testCA.crl";
 DistributionPoint dp = new DistributionPoint();
 dp.setDistributionPointNameURIs(new String[] { uri });
 
```
    If the distribution point name uses the nameRelativeToCRLIssuer choice the relative distinguished name (RDN) has to be appended to the X.500 distinguished name of the crl issuer to give the actual distribution point name (the crl issuer may be specified by the cRLIssuer field (e.g. indirect crl) or may be given by the issuer field of the certificate (in this case the certificate issuer is also the crl issuer)), for instance:
```
 RDN distributionPointName = new RDN();
 ...
 // add AVAs as required
 distributionPointName.addAVA(...);
 ...
 // create distribution point
 DistributionPoint dp = new DistributionPoint();
 dp.setDistributionPointName(distributionPointName);
 
```
    Parameters:
    distributionPointName - the name to be set
    
    Throws:
    
    java.lang.IllegalArgumentException - if the given name is not an instance of RDN or GeneralNames
    See Also:
    GeneralNames, RDN
  - setDistributionPointNameURIs
```
public void setDistributionPointNameURIs(java.lang.String[] uriNames)
```
    Sets distribution point name values of type uniformResourceIdentifier that shall be included in this DistributionPoint.
    Distribution point names of type uniformResourceIdentifier are the most common types of distribution point names that may be included in a DistributionPoint. A distribution point name of type uniformResourceIdentifier points to a location from where the CRL can be obtained. If more than one distribution point name value is present, each value uses a different mechanism to point to the same CRL. For instance, a distribution point name may contain two uri values, one pointing to a "http" location (e.g. "http://democa.iaik.at/test.crl") and the second pointing to a "ldap" location (e.g. "ldap://demoldap.iaik.at/cn=TestCA,o=iaik,c=at?certificateRevocationList;binary"), e.g.:
```
 String httpUri = "http://democa.iaik.at/testCA.crl";
 String ldapUri = "ldap://demoldap.iaik.at/cn=TestCA,o=iaik,c=at?certificateRevocationList;binary";
 DistributionPoint dp = new DistributionPoint();
 dp.setDistributionPointNameURIs(new String[] { httpUri, ldapUri });
 
```
    Parameters:
    uriNames - a String array containing distribution point name values of type uniformResourceIdentifier to be set for this distribution point
  - setReasonFlags
```
public void setReasonFlags(int reasonFlags)
```
    Sets the reason flags parameter of this extension.
    For instance:
```
 DistributionPoint distributionPoint = ...;
 distributionPoint.setReasonFlags(DistributionPoint.keyCompromise);
 
```
    A value of -1 indicates that no reason is specified.
    Parameters:
    reasonFlags - the reasons value as int
  - setCrlIssuerName
```
public void setCrlIssuerName(X509Certificate crlIssuerCert)
```
    Sets the CRL Issuer parameter from the given crl issuer certificate. The CRL issuer field, if present, specifies the entity that issues the CRL. The CRL issuer field must be present if the crl issuer is not the same entity as the one that has issued the certificate that contains a CRLDistributionPoints extension with this distribution point. In this case the crl will be refered to as an indirect crl, e.g.:
    For instance:
```
 X509Certificate crlIssuerCert = ...;
 DistributionPoint dp = ...;
 dp.setCrlIssuerName(crlIssuerCert);
 
```
    The CRL issuer field also has to be present, if the distributionPoint field is not included. In this case the CRL issuer field must contain a Name that corresponds to an X.500 or LDAP directory from where the CRL can be obtained.
    Parameters:
    crlIssuerCert - the certificate of the CRL issuer
    
    Throws:
    
    java.lang.NullPointerException - if the subject field of the certificate of the crl issuer is empty
  - setCrlIssuerName
```
public void setCrlIssuerName(Name crlIssuerName)
```
    Sets the CRL Issuer parameter to the given crl issuer name. The CRL issuer field, if present, specifies the entity that issues the CRL. The CRL issuer field must be present if the crl issuer is not the same entity as the one that has issued the certificate that contains a CRLDistributionPoints extension with this distribution point. In this case the crl will be refered to as an indirect crl, e.g.:
```
 Name crlIssuer = ...;
 DistributionPoint dp = ...;
 dp.setCrlIssuerName(crlIssuer);
 
```
    The CRL issuer field also has to be present, if the distributionPoint field is not included. In this case the CRL issuer field must contain a Name that corresponds to an X.500 or LDAP directory from where the CRL can be obtained.
    Parameters:
    crlIssuerName - the crl issuer as distinguished name
  - setCrlIssuer
```
public void setCrlIssuer(GeneralNames crlIssuer)
```
    Sets the CRL Issuer parameter of this DistributionPoint. The CRL issuer field, if present, specifies the entity that issues the CRL. The CRL issuer field must be present if the crl issuer is not the same entity as the one that has issued the certificate that contains a CRLDistributionPoints extension with this distribution point. In this case the crl will be refered to as an indirect crl, e.g.:
    For instance:
```
 X509Certificate crlIssuerCert = ...;
 GeneralName crlIssuerName = new GeneralName(GeneralName.directoryName, (Name)crlIssuerCert.getSubjectDN());
 GeneralNames crlIssuer = new GeneralNames(crlIssuerName);
 DistributionPoint dp = ...;
 dp.setCrlIssuer(crlIssuer);
 
```
    The CRL issuer field also has to be present, if the distributionPoint field is not included. In this case the CRL issuer field must contain a Name that corresponds to an X.500 or LDAP directory from where the CRL can be obtained.
    Parameters:
    crlIssuer - the CRL Issuer value to be set as GeneralNames
  - getDistributionPointName
```
public ASN1Type getDistributionPointName()
```
    Returns the distribution point name of this distribution point.
    
    Returns:
    the name as GeneralNames or as RDN
    See Also:
    GeneralNames, RDN, setDistributionPointName(iaik.asn1.ASN1Type)
  - getDistributionPointNameURIs
```
public java.lang.String[] getDistributionPointNameURIs()
```
    Returns all distribution point name values of type uniformResourceIdentifier that are included in this DistributionPoint.
    Distribution point name values of type uniformResourceIdentifier are the most common types of distribution point name values that may be included in a DistributionPoint. A distribution point name value of type uniformResourceIdentifier points to a location from where the CRL can be obtained. If more than one distribution point name value is present, each value uses a different mechanism to point to the same CRL. For instance, a DistributionPointName may contain two uri values, one pointing to a "http" location (e.g. "http://democa.iaik.at/testCA.crl") and the second pointing to a "ldap" location (e.g. "ldap://demoldap.iaik.at/cn=TestCA,o=iaik,c=at?certificateRevocationList;binary"). In this sample, the two uri Strings "http://democa.iaik.at/testCA.crl" and "ldap://demoldap.iaik.at/cn=TestCA,o=iaik,c=at?certificateRevocationList;binary" will be returned by this method.
    
    Returns:
    all distribution point name values of type uniformResourceIdentifier as array of String objects; the array may be empty if no URI distribution point names are included in this DistributionPoint
  - getDistributionPointNameURIs
```
public java.lang.String[] getDistributionPointNameURIs(java.lang.String protocol)
```
    Returns all distribution point name values of type uniformResourceIdentifier of the given protocol that are included in this DistributionPoint.
    Distribution point name values of type uniformResourceIdentifier are the most common types of distribution point name values that may be included in a DistributionPoint. A distribution point name value of type uniformResourceIdentifier points to a location from where the CRL can be obtained. If more than one distribution point name value is present, each value uses a different mechanism to point to the same CRL. For instance, a DistributionPointName may contain two uri values, one pointing to a "http" location (e.g. "http://democa.iaik.at/testCA.crl") and the second pointing to a "ldap" location (e.g. "ldap://demoldap.iaik.at/cn=TestCA,o=iaik,c=at?certificateRevocationList;binary"). In this sample, the two uri Strings "http://democa.iaik.at/testCA.crl" and "ldap://demoldap.iaik.at/cn=TestCA,o=iaik,c=at?certificateRevocationList;binary" will be returned by this method.
    
    Parameters:
    protocol - the protocol of the uri (e.g. "http" or "ldap"); maybe null to return all distribution point name values
    
    Returns:
    all distribution point name values of type uniformResourceIdentifier of the given protocol as array of String objects; the array may be empty if no URI distribution point names (of the given protocol, if not null) are included in this DistributionPoint
  - containsUriDpName
```
public boolean containsUriDpName()
```
    Checks if this DistributionPoint contains any uri distribution point name.
    
    Returns:
    true if this DistributionPoint contains an distribution point name of type GeneralNames which contains a GeneralName of type uniformResourceIdentifier, false otherwise
  - getReasonFlags
```
public int getReasonFlags()
```
    Returns the reason flags specification of this distribution point.
    Note the "big endian" representation of the BIT STRING representing the reason flag value of this DistributionPoint: the least significant bit indicates the reason flag with the lowest bit value, meaning that the integer value 1 specifies the "unused" flag, and the integer value 64 (binary 1000000, hexadecimal 40) specifies the "certificateHold" purpose.
    
    Returns:
    the reason flags specification as int, or -1 indicating that no reason is specified
    See Also:
    setReasonFlags(int)
  - isSet
```
public boolean isSet(int reasonFlags)
```
    Checks whether the specified reasonFlags values are set. For example, dp.isSet(DistributionPoint.keyCompromise) returns true if the keyCompromise bit is set.
    
    Returns:
    true if the given reason flags are set, false if not
  - getCrlIssuer
```
public GeneralNames getCrlIssuer()
```
    Returns the CRL Issuer parameter of this distribution point, if set. The CRL issuer field, if present, specifies the entity that issues the CRL. The CRL issuer field must be present if the crl issuer is not the same entity as the one that has issued the certificate that contains a CRLDistributionPoints extension with this distribution point. In this case the crl will be refered to as an indirect crl.
    The CRL issuer field also has to be present, if the distributionPoint field is not included. In this case the CRL issuer field must contain a Name that corresponds to an X.500 or LDAP directory from where the CRL can be obtained.
    
    Returns:
    the CRL Issuer as GeneralNames object, or null if the CRL issuer field is not set
  - getCrlIssuerName
```
public Name getCrlIssuerName()
```
    Returns the CRL Issuer name of this distribution point, if set. The CRL issuer field, if present, specifies the entity that issues the CRL. The CRL issuer field must be present if the crl issuer is not the same entity as the one that has issued the certificate that contains a CRLDistributionPoints extension with this distribution point. In this case the crl will be refered to as an indirect crl.
    The CRL issuer field also has to be present, if the distributionPoint field is not included. In this case the CRL issuer field must contain a Name that corresponds to an X.500 or LDAP directory from where the CRL can be obtained.
    
    Returns:
    the CRL Issuer name, if the cRLIssuer GeneralNames field is present and contains a GeneralName of type directoryName; null otherwise
  - loadCrl
```
public X509CRL loadCrl()
                throws java.net.MalformedURLException,
                       java.io.IOException,
                       java.security.cert.CRLException
```
    Downloads the crl from an uri distribution point name (if this DistributionPoint contains an uri distribution point name).
    Distribution point name values of type uniformResourceIdentifier are the most common types of distribution point name values that may be included in a DistributionPoint. A distribution point name value of type uniformResourceIdentifier points to a location from where the CRL can be obtained. If more than one distribution point name value is present, each value uses a different mechanism to point to the same CRL. For instance, a DistributionPointName may contain two uri values, one pointing to a "http" location (e.g. "http://democa.iaik.at/testCA.crl") and the second pointing to a "ldap" location (e.g. "ldap://demoldap.iaik.at/cn=TestCA,o=iaik,c=at?certificateRevocationList;binary"). This method steps through all uri distribution point names included and tries to download the crl from them. In the sample above, this method first would connect to "http://democa.iaik.at/testCA.crl" and try to download the crl from it. If successful, the crl is returned. Otherwise the second (and in this example last) distribution point name "ldap://demoldap.iaik.at/cn=TestCA,o=iaik,c=at?certificateRevocationList;binary" is contacted to download the crl from it.
    If you want to be sure that this DistributionPoint contains an distribution point name of type uniformResourceIdentifier, you first may call method containsUriDpName:
```
 DistributionPoint dp = ...;
 if (dp.containsUriDpName()) {
   // download crl
   X509CRL crl = dp.loadCrl();
 }
 
```
    This method uses an java.net.URLConnection for downloading the crl. Thus only protocols can be supported for which an java.net.URLStreamHandler is available. Since the http protocol is supported by the JDK by default, this method can download crls from an http uri distribution point name. If you want to support ldap, too, you may have to register the IAIK LdapURLConnection implementation, e.g. by using the java.protocol.handler.pkgs system property:
```
 System.getProperties().put("java.protocol.handler.pkgs", "iaik.x509.net");
 
```
    In this case you will have to ensure that the Java Naming and Directory interface (JNDI) is available. For JDK versions >=1.3 the JNDI is included in the JDK, for JDK versions <1.3 you also will have to put jndi.jar, ldap.jar and providerutil.jar into your classpath which can be downloaded from the JNDI homepage at SUN: http://java.sun.com/products/jndi.
    If you expect to download a large crl you alternatively may call method loadCrlStream and use the stream based crl implementation of IAIK-JCE for parsing the crl.
    If this distribution point does not contain a uri distribution point name, but a RDN and/or cRLIssuer fields, you may use method loadCrl(String url, Name certificateIssuer) for downloading the crl from a specific entry of an ldap server.
    Returns:
    the crl downloaded from the uri distribution point
    
    Throws:
    
    java.net.MalformedURLException - if the url referenced by the distribution point name is invalid or the uri protocol is not supported, or no uri dostribution point name is included in this DistributionPoint
    
    java.io.IOException - if an I/O error occurs when trying to download the crl from the distribution point
    
    java.security.cert.CRLException - if an error occurs when parsing the crl
  - loadCrl
```
public X509CRL loadCrl(java.lang.String ldapUrl,
              Name crlIssuer)
                throws java.net.MalformedURLException,
                       java.io.IOException,
                       java.security.cert.CRLException
```
    Downloads the crl from the given ldap server url (if this DistributionPoint contains a RelativeDistinguished RDN distribution point name, or the distribution point name is not present but the cRLIssuer field is set).
    If the distribution point name is given as RelativeDistinguishedName, the RDN value has to be appended to the distinguished name of the CRL issuer to represent an entry in a X.500 or LDAP directory. If the cRLIssuer field is present (indirect CRL), it has to contain a distinguished name to which the distribution point name RDN has to be appended. Otherwise (if the cRLIssuer field is not set) the crl issuer is the same as the certificate issuer and the distribution point name RDN has to be appended to the distinguished name of the certificate (= crl) issuer.
    If the DistributionPointName field is not present, the cRLIssuer field must be present and must represent the DN of a X.500 or LDAP directory from which the crl can be obtained.
    In both cases the DistributionPoint only contains the DN pointing to an entry at the ldap directory, but does not contain the ldap server url itself. For that reason you have to specify the ldap server url when calling this method, e.g.:
```
 String url = "ldap://demoldap.iaik.at";
 Name crlIssuer = ...;
 DistributionPoint distributionPoint = ...;
 X509CRL crl = distributionPoint.loadCrl(url, crlIssuer);
 
```
    The crlIssuer only has to be specified if the cRLIssuer field of the DistributionPoint is not set and therefore the crl issuer is the same entity as the certificate issuer. For instance, let us assume, that the distributionPoint from above is included in a CRLDistributionPoints extension and contains a RDN distribution point name with "cn=crl". The crlIssuer shall be given as "cn=TestCA,o=iaik,c=at". In this case the crl is downloaded from the entry "cn=crl,cn=TestCA,o=iaik,c=at" from the ldap server running at "ldap://demoldap.iaik.at".
    This method uses a java.net.URLConnection for downloading the crl. Thus you will have to register the IAIK LdapURLConnection implementation, e.g. by using the java.protocol.handler.pkgs system property:
```
 System.getProperties().put("java.protocol.handler.pkgs", "iaik.x509.net");
 
```
    You also will have to ensure that the Java Naming and Directory interface (JNDI) is available. For JDK versions >=1.3 the JNDI is included in the JDK, for JDK versions <1.3 you also will have to put jndi.jar, ldap.jar and providerutil.jar into your classpath which can be downloaded from the JNDI homepage at SUN: http://java.sun.com/products/jndi.
    If you expect to download a large crl you alternatively may call method loadCrlStream(String ldapUrl, Name certificateIssuer) and use the stream based crl implementation of IAIK-JCE for parsing the crl.
    However, if this distribution point contains a uri distribution point name (most usually), you shall use method loadCrl() for downloading the crl from the distribution point name url.
    Parameters:
    ldapUrl - the url of the ldap server from which to download the crl at the entry referenced by this distribution point
    crlIssuer - the issuer of the crl (= issuer of the certificate); required if the crl referenced by this distribution point is NOT an indirect crl and therefore does not contain the cRLIssuer field
    
    Returns:
    the crl downloaded from an entry at the specified ldap server
    
    Throws:
    
    java.net.MalformedURLException - if the given ldap url is invalid or the ldap protocol is not supported
    
    java.io.IOException - if an I/O error occurs when trying to download the crl from the distribution point
    
    java.security.cert.CRLException - if an error occurs when parsing the crl
  - loadCrlStream
```
public java.io.InputStream loadCrlStream()
                                  throws java.net.MalformedURLException,
                                         java.io.IOException
```
    Connects to and downloads the crl from an uri distribution point name (if this DistributionPoint contains an uri distribution point name) and provides a input stream from where the crl can be read.
    This method may be called as alternative to method loadCrl when expecting to download a very large crl and wanting to use the stream based crl implementation of IAIK-JCE for parsing the crl.
    Distribution point name values of type uniformResourceIdentifier are the most common types of distribution point name values that may be included in a DistributionPoint. A distribution point name value of type uniformResourceIdentifier points to a location from where the CRL can be obtained. If more than one distribution point name value is present, each value uses a different mechanism to point to the same CRL. For instance, a DistributionPointName may contain two uri values, one pointing to a "http" location (e.g. "http://democa.iaik.at/testCA.crl") and the second pointing to a "ldap" location (e.g. "ldap://demoldap.iaik.at/cn=TestCA,o=iaik,c=at?certificateRevocationList;binary"). This method steps through all uri distribution point names included and tries to download the crl from them. In the sample above, this method first would connect to "http://democa.iaik.at/testCA.crl" and try to download the crl from it. If successful, a input stream is returned fron which the crl can be read. Otherwise the second (and in this example last) distribution point name "ldap://demoldap.iaik.at/cn=TestCA,o=iaik,c=at?certificateRevocationList;binary" is contacted to download the crl from it.
    If you want to be sure that this DistributionPoint contains an distribution point name of type uniformResourceIdentifier, you first may call method containsUriDpName:
```
 DistributionPoint dp = ...;
 if (dp.containsUriDpName()) {
   // download crl
   InputStream crlInputStream = dp.loadCrlStream();
   // certificates for which to ceck revocation status
   X509Certificate[] consideredCertificates = ...;
   // crl issuer cert
   X509Certificate crlIssuerCert = ...;
   // setup listener with all certificates of interest and public key of CRL signer
   RevokedCertificatesCRLListener listener = 
     new RevokedCertificatesCRLListener(consideredCertificates, crlIssuerCert.getPublicKey());
   // setup the CRL stream handler
    X509CRLStream crlStreamHandler = new X509CRLStream(listener);
   // and let is parse the CRL stream
   crlStreamHandler.parse(crlInputStream);
   // get a hashtable which contains all certificates which have been found in the
   // CRL and also were in the list of considered certificates.
   Hashtable revocationEntriesTable = listener.getRevokedCertificates();
   ...
 }
 
```
    This method uses an java.net.URLConnection for downloading the crl. Thus only protocols can be supported for which an java.net.URLStreamHandler is available. Since the http protocol is supported by the JDK by default, this method can download crls from an http uri distribution point name. If you want to support ldap, too, you may have to register the IAIK LdapURLConnection implementation, e.g. by using the java.protocol.handler.pkgs system property:
```
 System.getProperties().put("java.protocol.handler.pkgs", "iaik.x509.net");
 
```
    In this case you will have to ensure that the Java Naming and Directory interface (JNDI) is available. For JDK versions >=1.3 the JNDI is included in the JDK, for JDK versions <1.3 you also will have to put jndi.jar, ldap.jar and providerutil.jar into your classpath which can be downloaded from the JNDI homepage at SUN: http://java.sun.com/products/jndi.
    If this distribution point does not contain a uri distribution point name, but a RDN and/or cRLIssuer, you may use method loadCrlStream(String url, Name certificateIssuer) for downloading the crl from a specific entry of an ldap server.
    Returns:
    an input stream from which the crl can be read
    
    Throws:
    
    java.net.MalformedURLException - if the url referenced by the distribution point name is invalid or the uri protocol is not supported, or no uri dostribution point name is included in this DistributionPoint
    
    java.io.IOException - if an I/O error occurs when trying to download the crl from the distribution point
  - loadCrlStream
```
public java.io.InputStream loadCrlStream(java.lang.String ldapUrl,
                                Name crlIssuer)
                                  throws java.net.MalformedURLException,
                                         java.io.IOException
```
    Connects to and downloads the crl from the given ldap server url (if this DistributionPoint contains a RelativeDistinguished RDN distribution point name, or the distribution point name is not present but the cRLIssuer field is set).
    This method may be called as alternative to method loadCrl(String ldapUrl, Name crlIssuer) when expecting to download a very large crl and wanting to use the stream based crl implementation of IAIK-JCE for parsing the crl.
    If the distribution point name is given as RelativeDistinguishedName, the RDN value has to be appended to the distinguished name of the CRL issuer to represent an entry in a X.500 or LDAP directory. If the cRLIssuer field is present (indirect CRL), it has to contain a distinguished name to which the distribution point name RDN has to be appended. Otherwise (if the cRLIssuer field is not set) the crl issuer is the same as the certificate issuer and the distribution point name RDN has to be appended to the distinguished name of the certificate (= crl) issuer.
    If the DistributionPointName field is not present, the cRLIssuer field must be present and must represent the DN of a X.500 or LDAP directory from which the crl can be obtained.
    In both cases the DistributionPoint only contains the DN pointing to an entry at the ldap directory, but does not contain the ldap server url itself. For that reason you have to specify the ldap server url when calling this method, e.g.:
```
 String url = "ldap://demoldap.iaik.at";
 Name crlIssuer = ...;
 DistributionPoint distributionPoint = ...;
 InputStream crlInputStream = distributionPoint.loadCrlStream(url, crlIssuer);
 // certificates for which to ceck revocation status
 X509Certificate[] consideredCertificates = ...;
 // crl issuer cert
 X509Certificate crlIssuerCert = ...;
 // setup listener with all certificates of interest and public key of CRL signer
 RevokedCertificatesCRLListener listener = 
   new RevokedCertificatesCRLListener(consideredCertificates, crlIssuerCert.getPublicKey());
 // setup the CRL stream handler
 X509CRLStream crlStreamHandler = new X509CRLStream(listener);
 // and let is parse the CRL stream
 crlStreamHandler.parse(crlInputStream);
 // get a hashtable which contains all certificates which have been found in the
 // CRL and also were in the list of considered certificates.
 Hashtable revocationEntriesTable = listener.getRevokedCertificates();
 ...
 
```
    The crlIssuer only has to be specified if the cRLIssuer field of the DistributionPoint is not set and therefore the crl issuer is the same entity as the certificate issuer. For instance, let us assume, that the distributionPoint from above is included in a CRLDistributionPoints extension and contains a RDN distribution point name with "cn=crl". The crlIssuer shall be given as "cn=TestCA,o=iaik,c=at". In this case the crl is downloaded from the entry "cn=crl,cn=TestCA,o=iaik,c=at" from the ldap server running at "ldap://demoldap.iaik.at".
    This method uses a java.net.URLConnection for downloading the crl. Thus you will have to register the IAIK LdapURLConnection implementation, e.g. by using the java.protocol.handler.pkgs system property:
```
 System.getProperties().put("java.protocol.handler.pkgs", "iaik.x509.net");
 
```
    You also will have to ensure that the Java Naming and Directory interface (JNDI) is available. For JDK versions >=1.3 the JNDI is included in the JDK, for JDK versions <1.3 you also will have to put jndi.jar, ldap.jar and providerutil.jar into your classpath which can be downloaded from the JNDI homepage at SUN: http://java.sun.com/products/jndi.
    However, if this distribution point contains a uri distribution point name (most usually), you shall use method loadCrlStream() for downloading the crl from the distribution point name url.
    Parameters:
    ldapUrl - the url of the ldap server from which to download the crl at the entry referenced by this distribution point
    crlIssuer - the issuer of the crl (= issuer of the certificate); required if the crl referenced by this distribution point is NOT an indirect crl and therefore does not contain the cRLIssuer field
    
    Returns:
    an input stream from which the crl can be read
    
    Throws:
    
    java.net.MalformedURLException - if the given ldap url is invalid or the ldap protocol is not supported
    
    java.io.IOException - if an I/O error occurs when trying to download the crl from the distribution point
  - setLdapAttributeDescription
```
public void setLdapAttributeDescription(java.lang.String attributeDescription)
```
    Sets the attribute description to be used when downloading a crl from an ldap server.
    If the distribution point name of this DistributionPoint represents a GeneralNames fullName containing a uniformResourceIdentifier ldap url, the attribute description (e.g. "certificateRevocationList;binary") already will be included in the ldap url, for instance:
```
 "ldap://demoldap.iaik.at/CN=crl,CN=TestCA,O=iaik,C=at?certificateRevocationList;binary"
 
```
    In this case any attribute description set by this method is ignored.
    However, if the distribution point name is given as RelativeDistinguishedName, the RDN value has to be appended to the distinguished name of the CRL issuer to represent an entry in a X.500 or LDAP directory. In similar way, if the DistributionPointName field is not present, the cRLIssuer field must represent the DN of a X.500 or LDAP directory from which the crl can be obtained. In both cases, the attribute description (as required for ldap search) is not contained in the DistributionPoint and therefore it might be necessary to set it from outside before calling method loadCrl for downloading the crl from the ldap server. By default this method uses the attributeDescription "authorityRevocationList;binary,certificateRevocationList;binary" if the DistributionPoint belongs to a CRLDistributionPoints extension, and "deltaRevocationList;binary" if the DistributionPoint belongs to FreshestCRL extension. In the first case, when calling method loadCrl, the ldap server is searched for a authority or certificate revocation list, in the second case it is searched for a delta revocation list, e.g.:
```
 String url = "ldap://demoldap.iaik.at";
 Name crlIssuer = ...;
 DistributionPoint distributionPoint = ...;
 X509CRL crl = distributionPoint.loadCrl(url, crlIssuer);
 
```
    Let us assume, that the distributionPoint from above is included in a CRLDistributionPoints extension and contains a RDN distribution point name like "cn=crl". The crlIssuer shall be given as "cn=TestCA,o=iaik,c=at". In this case the entry "cn=crl,cn=TestCA,o=iaik,c=at" at the ldap server running at "ldap://demoldap.iaik.at" will be searched for an "authorityRevocationList;binary" or "certificateRevocationList;binary" attribute from which to get the crl. However, if the distributionPoint from above is included in a FreshestCRL extension, the "cn=crl,cn=TestCA,o=iaik,c=at" entry will be searched for a "certificateRevocationList;binary" attribute.
    You can use this method for explicitly setting the attribute description you want to use for searching the ldap directory, e.g.:
```
 String url = "ldap://demoldap.iaik.at";
 Name crlIssuer = ...;
 DistributionPoint distributionPoint = ...;
 distributionPoint.setLdapAttributeDescription("certificateRevocationList;binary");
 X509CRL crl = distributionPoint.loadCrl(url, crlIssuer);
 
```
    Parameters:
    attributeDescription - the attribute description to be used for ldap search (e.g. "certificateRevocationList;binary")
    
    Throws:
    
    java.lang.NullPointerException - if the given attribute description is null
    
    java.lang.IllegalArgumentException - if the given attributeDescription is invalid (not supported)
  - toString
```
public java.lang.String toString()
```
    Returns a string that represents the contents of this DistributionPoint.
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    the string representation

Class DistributionPoint

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

unused

keyCompromise

cACompromise

affiliationChanged

superseded

cessationOfOperation

certificateHold

privilegeWithdrawn

aACompromise

Constructor Detail

DistributionPoint

DistributionPoint

DistributionPoint

DistributionPoint

Method Detail

toASN1Object

setDistributionPointName

setDistributionPointNameURIs

setReasonFlags

setCrlIssuerName

setCrlIssuerName

setCrlIssuer

getDistributionPointName

getDistributionPointNameURIs

getDistributionPointNameURIs

containsUriDpName

getReasonFlags

isSet

getCrlIssuer

getCrlIssuerName

loadCrl

loadCrl

loadCrlStream

loadCrlStream

setLdapAttributeDescription

toString