Exemple #1
0
 /**
  * Returns the definition of the selected attribute / object class OID.
  *
  * @param schemaEntry The selected schema entry to search on.
  * @param type The type of the research. ("objectClasses" or "attributeTypes")
  * @param oid The OID of the element to search for.
  * @return The byte string definition of the element.
  */
 private static ByteString getSchemaElement(
     final Entry schemaEntry, final String type, final String oid) {
   final Attribute attribute = schemaEntry.getAttribute(type);
   final MatchingRule mrule = CoreSchema.getObjectIdentifierFirstComponentMatchingRule();
   Assertion assertion;
   try {
     assertion = mrule.getAssertion(ByteString.valueOfUtf8(oid));
     for (final ByteString value : attribute) {
       final ByteString nvalue = mrule.normalizeAttributeValue(value);
       if (assertion.matches(nvalue).toBoolean()) {
         return value;
       }
     }
   } catch (DecodeException e) {
     throw new IllegalStateException(e);
   }
   throw new IllegalStateException(ERR_UPGRADE_UNKNOWN_OC_ATT.get(type, oid).toString());
 }
Exemple #2
0
/**
 * The root DSE is a DSA-specific Entry (DSE) and not part of any naming context (or any subtree),
 * and which is uniquely identified by the empty DN.
 *
 * <p>A Directory Server uses the root DSE to provide information about itself using the following
 * set of attributes:
 *
 * <ul>
 *   <li>{@code altServer}: alternative Directory Servers
 *   <li>{@code namingContexts}: naming contexts
 *   <li>{@code supportedControl}: recognized LDAP controls
 *   <li>{@code supportedExtension}: recognized LDAP extended operations
 *   <li>{@code supportedFeatures}: recognized LDAP features
 *   <li>{@code supportedLDAPVersion}: LDAP versions supported
 *   <li>{@code supportedSASLMechanisms}: recognized SASL authentication mechanisms
 *   <li>{@code supportedAuthPasswordSchemes}: recognized authentication password schemes
 *   <li>{@code subschemaSubentry}: the name of the subschema subentry holding the schema
 *       controlling the Root DSE
 *   <li>{@code vendorName}: the name of the Directory Server implementer
 *   <li>{@code vendorVersion}: the version of the Directory Server implementation.
 * </ul>
 *
 * The values provided for these attributes may depend on session- specific and other factors. For
 * example, a server supporting the SASL EXTERNAL mechanism might only list "EXTERNAL" when the
 * client's identity has been established by a lower level.
 *
 * <p>The root DSE may also include a {@code subschemaSubentry} attribute. If it does, the attribute
 * refers to the subschema (sub)entry holding the schema controlling the root DSE. Clients SHOULD
 * NOT assume that this subschema (sub)entry controls other entries held by the server.
 *
 * @see <a href="http://tools.ietf.org/html/rfc4512">RFC 4512 - Lightweight Directory Access
 *     Protocol (LDAP): Directory Information Models </a>
 * @see <a href="http://tools.ietf.org/html/rfc3045">RFC 3045 - Storing Vendor Information in the
 *     LDAP Root DSE </a>
 * @see <a href="http://tools.ietf.org/html/rfc3112">RFC 3112 - LDAP Authentication Password Schema
 *     </a>
 */
public final class RootDSE {
  private static final AttributeDescription ATTR_ALT_SERVER =
      AttributeDescription.create(CoreSchema.getAltServerAttributeType());

  private static final AttributeDescription ATTR_NAMING_CONTEXTS =
      AttributeDescription.create(CoreSchema.getNamingContextsAttributeType());

  private static final AttributeDescription ATTR_SUBSCHEMA_SUBENTRY =
      AttributeDescription.create(CoreSchema.getSubschemaSubentryAttributeType());

  private static final AttributeDescription ATTR_SUPPORTED_AUTH_PASSWORD_SCHEMES =
      AttributeDescription.create(CoreSchema.getSupportedAuthPasswordSchemesAttributeType());

  private static final AttributeDescription ATTR_SUPPORTED_CONTROL =
      AttributeDescription.create(CoreSchema.getSupportedControlAttributeType());

  private static final AttributeDescription ATTR_SUPPORTED_EXTENSION =
      AttributeDescription.create(CoreSchema.getSupportedExtensionAttributeType());

  private static final AttributeDescription ATTR_SUPPORTED_FEATURE =
      AttributeDescription.create(CoreSchema.getSupportedFeaturesAttributeType());

  private static final AttributeDescription ATTR_SUPPORTED_LDAP_VERSION =
      AttributeDescription.create(CoreSchema.getSupportedLDAPVersionAttributeType());

  private static final AttributeDescription ATTR_SUPPORTED_SASL_MECHANISMS =
      AttributeDescription.create(CoreSchema.getSupportedSASLMechanismsAttributeType());

  private static final AttributeDescription ATTR_VENDOR_NAME =
      AttributeDescription.create(CoreSchema.getVendorNameAttributeType());

  private static final AttributeDescription ATTR_VENDOR_VERSION =
      AttributeDescription.create(CoreSchema.getVendorNameAttributeType());

  private static final AttributeDescription ATTR_FULL_VENDOR_VERSION =
      AttributeDescription.create(CoreSchema.getFullVendorVersionAttributeType());

  private static final SearchRequest SEARCH_REQUEST =
      Requests.newSearchRequest(
          DN.rootDN(),
          SearchScope.BASE_OBJECT,
          Filter.objectClassPresent(),
          ATTR_ALT_SERVER.toString(),
          ATTR_NAMING_CONTEXTS.toString(),
          ATTR_SUPPORTED_CONTROL.toString(),
          ATTR_SUPPORTED_EXTENSION.toString(),
          ATTR_SUPPORTED_FEATURE.toString(),
          ATTR_SUPPORTED_LDAP_VERSION.toString(),
          ATTR_SUPPORTED_SASL_MECHANISMS.toString(),
          ATTR_FULL_VENDOR_VERSION.toString(),
          ATTR_VENDOR_NAME.toString(),
          ATTR_VENDOR_VERSION.toString(),
          ATTR_SUPPORTED_AUTH_PASSWORD_SCHEMES.toString(),
          ATTR_SUBSCHEMA_SUBENTRY.toString(),
          "*");

  /**
   * Asynchronously reads the Root DSE from the Directory Server using the provided connection.
   *
   * <p>If the Root DSE is not returned by the Directory Server then the request will fail with an
   * {@link EntryNotFoundException}. More specifically, the returned promise will never return
   * {@code null}.
   *
   * @param connection A connection to the Directory Server whose Root DSE is to be read.
   * @param handler A result handler which can be used to asynchronously process the operation
   *     result when it is received, may be {@code null}.
   * @return A promise representing the result of the operation.
   * @throws UnsupportedOperationException If the connection does not support search operations.
   * @throws IllegalStateException If the connection has already been closed, i.e. if {@code
   *     isClosed() == true}.
   * @throws NullPointerException If the {@code connection} was {@code null}.
   */
  public static LdapPromise<RootDSE> readRootDSEAsync(
      final Connection connection, final ResultHandler<? super RootDSE> handler) {
    return connection
        .searchSingleEntryAsync(SEARCH_REQUEST)
        .then(
            new Function<SearchResultEntry, RootDSE, LdapException>() {
              @Override
              public RootDSE apply(SearchResultEntry result) {
                return valueOf(result);
              }
            });
  }

  /**
   * Reads the Root DSE from the Directory Server using the provided connection.
   *
   * <p>If the Root DSE is not returned by the Directory Server then the request will fail with an
   * {@link EntryNotFoundException}. More specifically, this method will never return {@code null}.
   *
   * @param connection A connection to the Directory Server whose Root DSE is to be read.
   * @return The Directory Server's Root DSE.
   * @throws LdapException If the result code indicates that the request failed for some reason.
   * @throws UnsupportedOperationException If the connection does not support search operations.
   * @throws IllegalStateException If the connection has already been closed, i.e. if {@code
   *     isClosed() == true}.
   * @throws NullPointerException If the {@code connection} was {@code null}.
   */
  public static RootDSE readRootDSE(final Connection connection) throws LdapException {
    final Entry entry = connection.searchSingleEntry(SEARCH_REQUEST);
    return valueOf(entry);
  }

  /**
   * Creates a new Root DSE instance backed by the provided entry. Modifications made to {@code
   * entry} will be reflected in the returned Root DSE. The returned Root DSE instance is
   * unmodifiable and attempts to use modify any of the returned collections will result in a {@code
   * UnsupportedOperationException}.
   *
   * @param entry The Root DSE entry.
   * @return A Root DSE instance backed by the provided entry.
   * @throws NullPointerException If {@code entry} was {@code null} .
   */
  public static RootDSE valueOf(Entry entry) {
    Reject.ifNull(entry);
    return new RootDSE(entry);
  }

  private final Entry entry;

  /** Prevent direct instantiation. */
  private RootDSE(final Entry entry) {
    this.entry = entry;
  }

  /**
   * Returns an unmodifiable list of URIs referring to alternative Directory Servers that may be
   * contacted when the Directory Server becomes unavailable.
   *
   * <p>URIs for Directory Servers implementing the LDAP protocol are written according to RFC 4516.
   * Other kinds of URIs may be provided.
   *
   * <p>If the Directory Server does not know of any other Directory Servers that could be used, the
   * returned list will be empty.
   *
   * @return An unmodifiable list of URIs referring to alternative Directory Servers, which may be
   *     empty.
   * @see <a href="http://tools.ietf.org/html/rfc4516">RFC 4516 - Lightweight Directory Access
   *     Protocol (LDAP): Uniform Resource Locator </a>
   */
  public Collection<String> getAlternativeServers() {
    return getMultiValuedAttribute(ATTR_ALT_SERVER, Functions.byteStringToString());
  }

  /**
   * Returns the entry which backs this Root DSE instance. Modifications made to the returned entry
   * will be reflected in this Root DSE.
   *
   * @return The underlying Root DSE entry.
   */
  public Entry getEntry() {
    return entry;
  }

  /**
   * Returns an unmodifiable list of DNs identifying the context prefixes of the naming contexts
   * that the Directory Server masters or shadows (in part or in whole).
   *
   * <p>If the Directory Server does not master or shadow any naming contexts, the returned list
   * will be empty.
   *
   * @return An unmodifiable list of DNs identifying the context prefixes of the naming contexts,
   *     which may be empty.
   */
  public Collection<DN> getNamingContexts() {
    return getMultiValuedAttribute(ATTR_NAMING_CONTEXTS, Functions.byteStringToDN());
  }

  /**
   * Returns a string which represents the DN of the subschema subentry holding the schema
   * controlling the Root DSE.
   *
   * <p>Clients SHOULD NOT assume that this subschema (sub)entry controls other entries held by the
   * Directory Server.
   *
   * @return The DN of the subschema subentry holding the schema controlling the Root DSE, or {@code
   *     null} if the DN is not provided.
   */
  public DN getSubschemaSubentry() {
    return getSingleValuedAttribute(ATTR_SUBSCHEMA_SUBENTRY, Functions.byteStringToDN());
  }

  /**
   * Returns an unmodifiable list of supported authentication password schemes which the Directory
   * Server supports.
   *
   * <p>If the Directory Server does not support any authentication password schemes, the returned
   * list will be empty.
   *
   * @return An unmodifiable list of supported authentication password schemes, which may be empty.
   * @see <a href="http://tools.ietf.org/html/rfc3112">RFC 3112 - LDAP Authentication Password
   *     Schema </a>
   */
  public Collection<String> getSupportedAuthenticationPasswordSchemes() {
    return getMultiValuedAttribute(
        ATTR_SUPPORTED_AUTH_PASSWORD_SCHEMES, Functions.byteStringToString());
  }

  /**
   * Returns an unmodifiable list of object identifiers identifying the request controls that the
   * Directory Server supports.
   *
   * <p>If the Directory Server does not support any request controls, the returned list will be
   * empty. Object identifiers identifying response controls may not be listed.
   *
   * @return An unmodifiable list of object identifiers identifying the request controls, which may
   *     be empty.
   */
  public Collection<String> getSupportedControls() {
    return getMultiValuedAttribute(ATTR_SUPPORTED_CONTROL, Functions.byteStringToString());
  }

  /**
   * Returns an unmodifiable list of object identifiers identifying the extended operations that the
   * Directory Server supports.
   *
   * <p>If the Directory Server does not support any extended operations, the returned list will be
   * empty.
   *
   * <p>An extended operation generally consists of an extended request and an extended response but
   * may also include other protocol data units (such as intermediate responses). The object
   * identifier assigned to the extended request is used to identify the extended operation. Other
   * object identifiers used in the extended operation may not be listed as values of this
   * attribute.
   *
   * @return An unmodifiable list of object identifiers identifying the extended operations, which
   *     may be empty.
   */
  public Collection<String> getSupportedExtendedOperations() {
    return getMultiValuedAttribute(ATTR_SUPPORTED_EXTENSION, Functions.byteStringToString());
  }

  /**
   * Returns an unmodifiable list of object identifiers identifying elective features that the
   * Directory Server supports.
   *
   * <p>If the server does not support any discoverable elective features, the returned list will be
   * empty.
   *
   * @return An unmodifiable list of object identifiers identifying the elective features, which may
   *     be empty.
   */
  public Collection<String> getSupportedFeatures() {
    return getMultiValuedAttribute(ATTR_SUPPORTED_FEATURE, Functions.byteStringToString());
  }

  /**
   * Returns an unmodifiable list of the versions of LDAP that the Directory Server supports.
   *
   * @return An unmodifiable list of the versions.
   */
  public Collection<Integer> getSupportedLDAPVersions() {
    return getMultiValuedAttribute(ATTR_SUPPORTED_LDAP_VERSION, Functions.byteStringToInteger());
  }

  /**
   * Returns an unmodifiable list of the SASL mechanisms that the Directory Server recognizes and/or
   * supports.
   *
   * <p>The contents of the returned list may depend on the current session state and may be empty
   * if the Directory Server does not support any SASL mechanisms.
   *
   * @return An unmodifiable list of the SASL mechanisms, which may be empty.
   * @see <a href="http://tools.ietf.org/html/rfc4513">RFC 4513 - Lightweight Directory Access
   *     Protocol (LDAP): Authentication Methods and Security Mechanisms </a>
   * @see <a href="http://tools.ietf.org/html/rfc4422">RFC 4422 - Simple Authentication and Security
   *     Layer (SASL) </a>
   */
  public Collection<String> getSupportedSASLMechanisms() {
    return getMultiValuedAttribute(ATTR_SUPPORTED_SASL_MECHANISMS, Functions.byteStringToString());
  }

  /**
   * Returns a string which represents the name of the Directory Server implementer.
   *
   * @return The name of the Directory Server implementer, or {@code null} if the vendor name is not
   *     provided.
   * @see <a href="http://tools.ietf.org/html/rfc3045">RFC 3045 - Storing Vendor Information in the
   *     LDAP Root DSE </a>
   */
  public String getVendorName() {
    return getSingleValuedAttribute(ATTR_VENDOR_NAME, Functions.byteStringToString());
  }

  /**
   * Returns a string which represents the version of the Directory Server implementation.
   *
   * <p>Note that this value is typically a release value comprised of a string and/or a string of
   * numbers used by the developer of the LDAP server product. The returned string will be unique
   * between two versions of the Directory Server, but there are no other syntactic restrictions on
   * the value or the way it is formatted.
   *
   * @return The version of the Directory Server implementation, or {@code null} if the vendor
   *     version is not provided.
   * @see <a href="http://tools.ietf.org/html/rfc3045">RFC 3045 - Storing Vendor Information in the
   *     LDAP Root DSE </a>
   */
  public String getVendorVersion() {
    return getSingleValuedAttribute(ATTR_VENDOR_VERSION, Functions.byteStringToString());
  }

  /**
   * Returns a string which represents the full version of the Directory Server implementation.
   *
   * @return The full version of the Directory Server implementation, or {@code null} if the vendor
   *     version is not provided.
   */
  public String getFullVendorVersion() {
    return getSingleValuedAttribute(ATTR_FULL_VENDOR_VERSION, Functions.byteStringToString());
  }

  private <N> Collection<N> getMultiValuedAttribute(
      final AttributeDescription attributeDescription,
      final Function<ByteString, N, NeverThrowsException> function) {
    // The returned collection is unmodifiable because we may need to
    // return an empty collection if the attribute does not exist in the
    // underlying entry. If a value is then added to the returned empty
    // collection it would require that an attribute is created in the
    // underlying entry in order to maintain consistency.
    final Attribute attr = entry.getAttribute(attributeDescription);
    if (attr != null) {
      return Collections.unmodifiableCollection(
          Collections2.transformedCollection(attr, function, Functions.objectToByteString()));
    } else {
      return Collections.emptySet();
    }
  }

  private <N> N getSingleValuedAttribute(
      final AttributeDescription attributeDescription,
      final Function<ByteString, N, NeverThrowsException> function) {
    final Attribute attr = entry.getAttribute(attributeDescription);
    if (attr == null || attr.isEmpty()) {
      return null;
    } else {
      return function.apply(attr.firstValue());
    }
  }
}