7.10 Key distribution system

In order to establish a cross-server, cross-project, and cross-organization trust relationship, the Limax integrates the Key distribution system, which implements a safe and reliable Key distribution based on the PKIX framework. The obtained Key can be used to sign and encrypt, to ensure the safe sharing of the information between the trusted systems.

  • 7.10.1 Design principles

    • Fundamental

      • 1. The server maintains a masterKey array of timed-generated random numbers, using timestamp index.

      • 2. The client side generates a nonce, along with the trusted domain name group to send to the server.

      • 3. The server executes key = Hash(masterKey, nonce, group). The timestamp and key are sent back to client side.

      • 4. The client side combines the timestamp, nonce and group to form the keyIdent.

      • 5. The client side uses key to sign or encrypt the message, along with the keyIdent to send to the receiving client.

      • 6. The receving client uses keyIdent to request the corresponding key from the server, to verify or decrypt the message.


    • Trust relationship design

      • 1. Establish the trust relationship through agreeing the certificate sign mode.

      • 2. Use KDSName to agree the Key distribution sytem name, which must uses a valid domain name.

      • 3. The RDN CommonName in the Subject of the server certificate specifies KDSName, and the other RDN has no agreement.

      • 4. All the server certificates in the same Key distribution system must be signed by the same CA.

      • 5. The SubjectAltName in the client certificate must have a DNS entry, which specifies the KDSName.

      • 6. The SubjectAltName in the client certificate can have multiple URI entries, which specify the group.

      • 7. The client certificates signed by the same CA have the same KDSName and group, and trust each other in the Key distribution system. For example, the same CA signs the client certificate for the system A, B, and C, using the same KDSName, where A contains the group G0 and G1, B contains the group G0 and G1, and C contains the group G0. In the G0, A, B and C can communicate with each other, and in the G1, A and B can communicate with each other.

      • 8. The CA which issues the client certificate does not necessarily need to be the same as the CA which issues the server certificate. The client certificates signed by the different CA with the same KDSName and group have no trust relationship. (When generating the Key on the implementation, the client certificate's issuer also participate the HASH calculation at the same time.)


    • Server design essential

      • 1. The server certificate signed by the same CA has the same KDSName, and uniquely determines a Key service network.

      • 2. Regularly generate the new masterKey, and distribute the key for the message sending client. The old masterKey should retain a certain period of time, to ensure that message receiving client can use keyIdent to restore the previous key.

      • 3. The Key service network is designed as a P2P network based on DHT, and the masterKey arrary is distributed on the service network. In the P2P mode, the size of the service network has no limit to ensure the system robustness in the maximum.


    • Client design essential

      • 1. The nonce is generated with the current time, and cache the server response if possible to minimize the server load and reduce the chance of the client block.

      • 2. The generation accuracy of nonce is adjustable, and can be directly agreed when signing the certificate. The group is represented with URI, using the fragment part of URI. For example, G0#10s, agrees that when using group G0, generates the nonce with 10s as the unit. The permitted units are s, m and h, respectively as second, minute and hour. If there is no unit, the default is milliseconds. If the fragment does not exist or parse fails, the system default parameters are used, and fragment is not part of group.

      • 3. Before initiating a request, the client checks the group legitimacy with its own certificate in advance, to avoid increasing the uncessary network spending. Certainly, this does not prevent the server performing the check.

  • 7.10.2 Server operating


    • Sign certificate

      This signed server certificate agrees the Key distribution system key.limax-project.org.


    • Server configuration(keyserver.xml)

      Top-level KeyServer elements, 8 properties.

      location：the location of server certificate.

      passphrase：the enable password of the location private key. In the actual operation, this property should not be filled and should be entered when launching the server.

      trustsPath：the trusted certificate path. The location includes the ROOTCA derivated from this certificate. If it needs to trust the other ROOTCA (or the current ROOTCA will expire soon, the new ROOTCA should be placed here), it should configure the trustsPath. The trustsPath can be a file or a directory. If it is a directory, traverse one level, and get the file. The file allows any certificate format, including CER, DER, PKCS7, PKCS12, and KeyStore, from which the ROOTCA is obtained, ignoring all errors.

      revocationCheckerOptions：the option that the server checks the certificate recovery status of the peer. The optional values are DISABLE, NO_FALLBACK, ONLY_END_ENTITY, PREFER_CRLS, and SOFT_FAIL. Case is not sensitive. The definitions of the last four parameters refer to java.security.cert.PKIXRevocationChecker.Option. The DISABLE has the highest priority. If the DISABLE is configured, the other configuration has no meaning.

      algorithm：specifies the HASH algorithm. The HASH algorithm determines the Key length returned to the client by server, for example, SHA1 returns 160-bit Key, and SHA-256 returns 256-bit Key.

      master：specifies a portal server list of P2P network, with comma to separate. It can be domain name, or IP.

      keyLifespan：the life cycle of masterKey, with day as unit. The masterKey which exceeds the life cyle will be deleted by server.

      publishPeriod：the release cycle of masterKey, with day as unit. When a new publish period begins, the server releases a new masterKey to the network. The server without configuring this property does not participate in this publication. In theory, only a publisher can be existed within a service network. In reality, multiple publishers can be configured to guarantee the redundancy, referring to the advanced topic.


    • Server running


      java –jar limax.jar keyserver [path to keyserver.xml]

      A keyserver.dht file will be generated in the keyserver.xml directory. This file is updated regularly, and saves the DHT neighbor information in the P2P network, which is helpful to quickly establish the neighbor relationship when restarting the server and should not be deleted.

  • 7.10.3 Client development


    • Sign certificate

      This signed client certificate specifies that the client uses Key distribution system key.limax-project.org, with two groups of prjA and prjB, where prjA uses 10 seconds nonce to generate precision.


    • Programming interface

      • 1. limax.key.KeyDesc, Key description class, provides two key methods.

        • 1.1. byte[] getIdent(); obtains the Key identity. The sender combines the identity to signature or encrypted message to send. The receiver uses the Key identity to request the corresponding Key to the server.

        • 1.2. byte[] getKey(); obtains the Key. The sender uses Key to sign or encrypt message. The receiver uses Key to verify or decrypt.

      • 2. KeyException, uses KeyException.Type getType() to return correspondind exception.

        • 2.1. SubjectAltNameWithoutDNSName, certificate signing error, SubjectAltName does not contain DNS type entry.

        • 2.2. SubjectAltNameWithoutURI, certificate signing error, SubjectAltName does not contain URI entry.

        • 2.3. MalformedKeyIdent, key identity decoding exception, usually is tampered during transmission and the message is not trusted.

        • 2.4. UnsupportedURI, the current client certificate does not support specified group.

        • 2.5. ServerRekeyed, the server can not generate a Key with specified timestamp. Usually the masterKey corresponding to timestamp expires, in which case the message receiver should re-request the message from the sender.

      • 3. limax.key.KeyAllocator, Key allocator class

        • 3.1. KeyAllocator(SSLContextAllocator sslContextAllocator), uses sslContextAllocator to construct a Key allocator, and the cache capacity is 1024. The possible thrown exception types are SubjectAltNameWithoutDNSName and SubjectAltNameWithoutURI.

        • 3.2. KeyAllocator(SSLContextAllocator sslContextAllocator, int cacheCapacity), uses sslContextAllocator to construct a Key allocator, with specified cache capacity. The possible thrown exception types are SubjectAltNameWithoutDNSName and SubjectAltNameWithoutURI.

        • 3.3. KeyDesc createKeyDesc(java.net.URI uri), the message sender, requests a KeyDesc, using the group specified by uri, and the fragment part of uri is ignored. The possible thrown exception type is UnsupportedURI. If the exception other than KeyException is thrown, it is usually a network error that can be re-tried.

        • 3.4. KeyDesc createKeyDesc(byte[] ident), the message receiver, uses the received Key identity to request KeyDesc. The possible thrown exception types are MalformedKeyIdent，UnsupportedURI and ServerRekeyed. If the exception other than KeyException is thrown, it is usually a network error that can be re-tried.

        • 3.5. String getDNSName(), gets the signed DNSName of the client certificate.

        • 3.6. Map<URI,Long> getURIs(), gets the signed group information of the client certificate. The Value of Ma is nonce precision, with milliseconds as unit.

        • 3.7. void setHost(java.lang.String httpsHost), specifies the domain name or IP address of partial Key server in the accessed Key service network. If this method is not used to configure the server address, the default is the domain name returned by getDNSName(). If the domain name resolves multiple IP addresses, these IP addresses are accessed one by one until no network error occurs or all errors occur and throw network exception.

        • 3.8. String getHost(), returns the domain name or IP of current used Key server.

      • 4. System properties

        • 4.1. limax.key.KeyAllocator.DEFAULT_PRECISION, nonce precision, with milliseconds as unit, and the default is 3600000.

        • 4.2. limax.key.KeyAllocator.TIMEOUT, network access timeout, with milliseconds as unit, and the default is 3000.


    • Application implementation essential

      • 1. If the service provider provides a new ROOTCA, add in via SSLContextAllocator.addTrust.

      • 2. Determine whether the SSLContextAllocator.setRecovationCheckerOptions is needed according to the suggestion from the service provider.

      • 3. Determine the KeyAllocator.setHost according to the configuration from the service provider.

      • 4. KeyAllocator.createKeyDesc, correctly classifies the exception. The KeyException type is an unrecoverable exception, and may need to check the certificate configuration, or request the message sender to re-send. Other Exception is network exception like timeout (this kind of exception should be very little and refer to advanced topic), and the re-try operation should be priorly considered. The only exception is that the certificate expiration causes the connection to be reset, and the warning "Certificate renew fail" in the log should be confirmed.

      • 5. Should design their own expire mechanism for the message. The masterKey life should only be understood as the maximum value of expire.


Prev Next