anchor.diff:  
   ==== Make changes to "apiman.properties"
   Once Elasticsearch is running smoothly, you must make some changes to the *apiman.properties*
  -file in order to tell apiman to use ES instead of a database.  You should modify the 
  +file in order to tell apiman to use ES instead of a database.  You should modify the
   apiman.properties file to have the following properties set:
   
   ----
  
positive.code: 
  
  == HowTos
  This section contains specific instructions for how to configure apiman for specific scenarios. 
  For example, it is possible to use Elasticsearch instead of Infinispan for certain API Gateway
  components.  This section details how to make these sorts of changes.
  
  
negative.code: 4. Configure one or more Service to use MTLS
  
  ==== Create Trust and Key Stores
  Please refer to https://docs.oracle.com/javase/7/docs/technotes/tools/solaris/keytool.html[official JDK documentation]
  to learn how to create and managed your SSL Trust and Key stores. Minimally a Keystore
  is required in order to successfully utilise MTLS, and in many cases also a Truststore.
  
  A *keystore* contains a given node's private key material, and must be kept safe.
  Each node should have a unique key entry. For instance, a gateway should have its
  own keystore, and each service likewise. In a production system, these keys should
  be issued by a trusted certificate authority.
  
  A *truststore* typically contains a set of certificate authorities which are trusted issuers.
  Therefore, any certificate signed by the trusted CA would be trusted by the gateway. If
  no truststore is explicitly provided to apiman the
  https://docs.oracle.com/javase/7/docs/technotes/tools/solaris/keytool.html#cacerts[default trusted certificates]
  provided by the JVM will be used. A typical use-case would be that an organization's
  internal signing authority is marked as trusted within in the truststore,
  and as the authority has been used to sign the certificate material in the keystores,
  they will mutually trust each other by virtue of the issuer.
  
  It is also possible to directly insert the *public/self-signed certificate* corresponding
  to a given private key pair into a truststore, which works well at small scales and for development, but will
  quickly cause the accumulation of a huge number of certificates in larger systems as
  it requires a 1:1 mapping of certificates and private keys (rather than 1:N by using a trusted authority).
  
  Your back-end services must be SSL enabled and *require authenticated client SSL connections*.
  This means you must have server SSL certificates generated (and appropriate certificates and/or
  CAs stored in your Trust Store).
  
  ==== Example Scenarios
  
  There are many potential configuration permutations, but we'll outline a few simple ones here to
  get you started.
  
  ===== Development Setup
  
  In our hypothetical development setup, let's imagine we have two services and a single gateway.
  
  [cols="1,1,2", options="header"]
  .Simple Development MTLS Setup
  |===
  |Component
  |Key Alias
  |Truststore's Trusted Certificates
  
  |Apiman Gateway
  |gateway
  |service_a.cer, service_b.cer
  
  |Service A
  |service_a
  |gateway.cer
  
  |Service B
  |service_b
  |gateway.cer
  
  |===
  
  .Walkthrough
  * Generate a keystore and export a certificate for each component:
  
      ** Gateway:
  
        keytool -genkey -keyalg RSA -keystore gateway_ks.jks -alias gateway
        keytool -export -alias gateway -file gateway.cer -keystore gateway_ks.jks
  
      ** Service A:
  
        keytool -genkey -keyalg RSA -keystore service_a_ks.jks -alias service_a
        keytool -export -alias service_a -file service_a.cer -keystore service_a_ks.jks
  
      ** Service B:
  
        keytool -genkey -keyalg RSA -keystore service_b_ks.jks -alias service_b
        keytool -export -alias service_b -file service_b.cer -keystore service_b_ks.jks
  
  * Import certificates into appropriate trust stores:
  
    ** Gateway:
  
      keytool -import -file service_a.cer -alias service_a -keystore gateway_ts.jks
      keytool -import -file service_b.cer -alias service_b -keystore gateway_ts.jks
  
    ** Service A:
  
      keytool -import -file gateway.cer -alias gateway -keystore service_a_ts.jks
  
    ** Service B:
  
      keytool -import -file gateway.cer -alias gateway -keystore service_b_ts.jks
  
  Now simply set the appropriate paths to the keystore and truststore in
  `apiman.properties` for the gateway, and set up your services with their respective
  truststores and keystores (the specifics of how to do this will depend on your
  service's implementation).
  
  We will also set the following in `apiman.properties` to make our development
  easier:
  
    apiman-gateway.connector-factory.tls.allowAnyHost=true
  
  When you add your MTLS protected services into apiman, you should set the
  `API Security` field to `MTLS/Two-Way-SSL`.
  
  ===== MTLS via Custom Certificate Authority
  
  The previous approach works for development, but doesn't scale well, is harder to manage
  and doesn't gracefully handle revocations, expiry, expansion, etc. Instead, let's
  summarise a scenario where an organisation has an internal CA which they use to
  sign service's certificates. The process for generating a CA and signing
  certificates is out of scope for this guide, but is trivial to accomplish using
  OpenSSL, LibreSSL, or similar.
  
  Let's imagine we have a CA called `apimanCA`, and have *signed* the certificates
  for each node.
  
  [cols="3", options="header"]
  .CA-based MTLS Setup
  |===
  |Component
  |Signed Key Alias
  |Truststore Contents
  
  |Apiman Gateway
  |gateway (signed by apimanCA)
  |apimanCA.cer
  
  |Service A
  |service_a (signed by apimanCA)
  |apimanCA.cer
  
  |Service N
  |service_n (signed by apimanCA)
  |apimanCA.cer
  
  |===
  
  Despite the initial administrative work setting up the CA and signing the
  certificates, this process is drastically less effort to maintain in large
  deployments. Only the trusted CA needs to be in the truststore, and any
  certificates signed by it are trusted by virtue of this.
  sign it with our trusted CA.
  
  ==== Make changes to "apiman.properties"
  Once you have your Trust Store and Key Store properly configured, you must
  configure your apiman.properties file.  Here is a summary of the properties:
  
  Omit any properties which are not relevant to you, with the exception of
  `trustStore`, which is mandatory for MTLS.
  
  ----
  # ---------------------------------------------------------------------
  # SSL/TLS settings for the gateway connector(s).
  # ---------------------------------------------------------------------
  
  # Trust store contains certificate(s) trusted by gateway.
  apiman-gateway.connector-factory.tls.trustStore=<PATH_TO_TRUST_STORE>
  