Provides an implementation of the `net.jini.discovery.x500.SHA1withDSA` discovery format, specified in the Jini Discovery and Join Specification. The {@link org.apache.river.discovery.x500.sha1withdsa.Client} class implements the client side of the `net.jini.discovery.x500.SHA1withDSA` discovery format for the multicast request and multicast announcement discovery protocols, while the {@link org.apache.river.discovery.x500.sha1withdsa.Server} class implements the server side of the discovery format for those protocols. Both classes are intended to be specified in a resource to configure the operation of the {@link org.apache.river.discovery.Discovery} class, as described in the documentation for {@link org.apache.river.discovery.Discovery#getProtocol2(ClassLoader)}.

## Supported Constraints

Both `Client` and `Server` support the following constraints for the multicast request protocol:

- a {@link net.jini.core.constraint.ConstraintAlternatives} if at least one element is supported
- {@link net.jini.core.constraint.Integrity#YES Integrity.YES}
- {@link net.jini.core.constraint.ClientAuthentication#YES ClientAuthentication.YES}
- {@link net.jini.core.constraint.Confidentiality#NO Confidentiality.NO}
- {@link net.jini.core.constraint.ServerAuthentication#NO ServerAuthentication.NO}
- {@link net.jini.core.constraint.Delegation#NO Delegation.NO}
- {@link net.jini.core.constraint.ClientMaxPrincipal}, when it contains an {@link javax.security.auth.x500.X500Principal} that has a DSA key as a private credential
- {@link net.jini.core.constraint.ClientMaxPrincipalType}, when it contains `X500Principal`
- {@link net.jini.core.constraint.ClientMinPrincipal}, when it contains a single `X500Principal` only, that has a DSA key as a private credential
- {@link net.jini.core.constraint.ClientMinPrincipalType}, when it contains `X500Principal` only
- any {@link net.jini.core.constraint.ServerMinPrincipal}
- any {@link net.jini.core.constraint.DelegationAbsoluteTime}
- any {@link net.jini.core.constraint.DelegationRelativeTime}

(Note that `ServerMinPrincipal`, `DelegationAbsoluteTime`, and `DelegationRelativeTime` constraints are trivially supported if `ServerAuthentication.YES` and `Delegation.YES` are not supported.)

Both `Client` and `Server` support the following constraints for the multicast announcement protocol:

- a {@link net.jini.core.constraint.ConstraintAlternatives} if at least one element is supported
- {@link net.jini.core.constraint.Integrity#YES Integrity.YES}
- {@link net.jini.core.constraint.ServerAuthentication#YES ServerAuthentication.YES}
- {@link net.jini.core.constraint.ClientAuthentication#NO ClientAuthentication.NO}
- {@link net.jini.core.constraint.Confidentiality#NO Confidentiality.NO}
- {@link net.jini.core.constraint.Delegation#NO Delegation.NO}
- {@link net.jini.core.constraint.ServerMinPrincipal}, when it contains a single `X500Principal` only, that has a DSA key as a private credential
- any {@link net.jini.core.constraint.ClientMaxPrincipal}
- any {@link net.jini.core.constraint.ClientMaxPrincipalType}
- any {@link net.jini.core.constraint.ClientMinPrincipal}
- any {@link net.jini.core.constraint.ClientMinPrincipalType}
- any {@link net.jini.core.constraint.DelegationAbsoluteTime}
- any {@link net.jini.core.constraint.DelegationRelativeTime}

(Note that `ClientMaxPricipal`, `ClientMaxPrincipalType`, `ClientMinPrincipal`, `ClientMinPrincipalType`, `DelegationAbsoluteTime`, and `DelegationRelativeTime` constraints are trivially supported if `ClientAuthentication.YES` and `Delegation.YES` are not supported.)

## System Properties

Both `Client` and `Server` can be configured through use of the following system properties:

`org.apache.river.discovery.x500.trustStore`
  This system property can be used to specify the location of an alternate truststore from which to obtain certificates for trusted entities. If this property is not specified, then the `javax.net.ssl.trustStore` system property is consulted. If that property is unspecified as well, then the `<java-home>/lib/security/cacerts` file is used. The applicable system property, if specified, is treated as a URL if it can be parsed as such; if it cannot be parsed, it is treated as a file name.

`org.apache.river.discovery.x500.trustStoreType`
  If the `org.apache.river.discovery.x500.trustStore` system property is being used to specify the truststore location, then this system property can be used to specify the type of the truststore to load. By default, the value returned by {@link java.security.KeyStore#getDefaultType} is used.

`org.apache.river.discovery.x500.trustStorePassword`
  If the `org.apache.river.discovery.x500.trustStore` system property is being used to specify the truststore location, then this system property can be used to specify the password for accessing the contents of the truststore. If it is not specified, then no password is used when accessing the truststore.

`org.apache.river.discovery.x500.ldapCertStores`
  This system property can be used to specify a list of LDAP-backed `CertStore`s to use for mapping received X.500 principals to corresponding X.509 certificates. If set, it should contain a comma-separated list of strings of the form `"<hostname>:<port>"` or `"<hostname>"`, where each string indicates the network address of an LDAP server to consult. If a given string does not specify a port, a default port number of `389` is used.

`javax.net.ssl.trustStore`
  If the `org.apache.river.discovery.x500.trustStore` system property is not set, then this system property can be used to specify the truststore from which to obtain certificates for trusted entities. If neither this property nor the `org.apache.river.discovery.x500.trustStore` property is specified, then the `<java-home>/lib/security/cacerts` file is used.

`javax.net.ssl.trustStoreType`
  If the `javax.net.ssl.trustStore` system property is being used to specify the truststore location, then this system property can be used to specify the type of the truststore to load. By default, the value returned by {@link java.security.KeyStore#getDefaultType} is used.

`javax.net.ssl.trustStorePassword`
  If the `javax.net.ssl.trustStore` system property is being used to specify the truststore location, then this system property can be used to specify the password for accessing the contents of the truststore. If it is not specified, then no password is used when accessing the truststore.

## Logging

Both `Client` and `Server` use the {@link java.util.logging.Logger} named `org.apache.river.discovery.x500` to log information at the following logging levels:

Level | Description
--- | ---
WARNING | Failure to initialize a certificate store
FINE | Exceptions mapping X.500 principals to X.509 certificates, as well as exceptions resulting from inadequate permissions to use private credentials corresponding to an X.500 principal
FINEST | Debugging trace information, such as the truststore and certificate stores in use, the X.500 principal used for signing a given packet, and the mapping of X.500 principals to corresponding X.509 certificates

@since 2.0 @see "Jini Discovery and Join Specification"