Limax Project

7.13 LimaxKey

LimaxKey is called Lmk for short, and supports certificate-based client login. The client login process uses a private key certificate package that is signed by convention. The signer information is included in the certificate content, and the user source can be traced very easily. In fact, Lmk provides a decentralized third-party login mechanism.

7.13.1 Design essential

1. To simplify the implementation of the client, the Lmk private key certificate package format LmkBundle is provided, and LmkBundle currently only supports RSA. The conversion tool between LmkBundle format and common formats such as PKCS12 is provided.

2. The implementation of the Lmk signing service is provided. The large-scale third-party organizations are supported, allowing ROOTCA to sign a specific third-party CA certificate LmkCA. LmkCA can only sign LmkBundles for its own users. The small and micro third-party agencies are supported, allowing generic CAs to sign their own users' LmkBundles for any third party organization.

3. Switcher and Auany help clients to renew certificates. After the client logs in, if Switcher or Auany detects that the client logs in using Lmk mode and reaches the certificate renew deadline, Switcher and Auany request the corresponding Lmk signing service to obtain a new LmkBundle and stores it on Auany. When the client logs in next time, LmkBundle is pushed to the client to save. (Of course, the client can also regularly get a new LmkBundle from its signing institution).

4. In certain circumstances, configuration is allowed to ignore certificate expiration detection.

5. LmkBundle can be used to bind login credentials. Such credentials use the certificate update time limit to determine the validity period. Expiration of the certificate will cause the client to re-bind the certificate by using Lmk. At this time, Auany helps the client to update the LmkBundle. When the next time the credentials are used to log in, the updated LmkBundle is also pushed to the client to save.

6. The pure HTML5 mode does not support Lmk login temporarily. The reason is that various browsers and HTTPS client certificate password prompts are not compatible. Saving automatic push private key certificate packages also suffers the installation restrictions of different operating systems.

7.13.2 Client development (using the java client as example)
- Relative classes and interfaces
  
  1. limax.endpoint.LmkBundle
```
LmkBundle LmkBundle.createInstance(Octets lmkdata, Octets passphrase);
```
  Create an LmkBundle. lmkdata is the private key certificate package file data signed for the users by the third-party organization that is stored on the client. Passphrase is the file password.
```
Octets LmkBundle.save(Octets passphrase);
```
  Allows the client itself to change the LmkBundle password and return new file data.
  
  2. limax.endpoint.LmkUpdater (delegate in C#, function object in C++)
```
void LmkUpdater.update(Octets lmkdata, Runnable done) throws Exception;
```
  Implement this interface and save the updated LmkBundle data pushed back by Switcher.After lmkdata saved run done.
  
  3. limax.endpoint.LoginConfig
  
  Among them, four versions of the LoginConfig.lmkLogin method use LmkBundle to create a login object.
```
LoginConfig.setLmkUpdater(LmkUpdater lmkUpdater);
```
  Install LmkUpdate object.
- Client implementation style code
```
LoginConfig loginConfig = LoginConfig.lmkLogin(LmkBundle.createInstance(
    Octets.wrap(Files.readAllBytes(Paths.get("/work/xxx.lmk"))),
    Octets.wrap("123456".getBytes())));
loginConfig.setLmkUpdater((lmkdata, done) -> {
    Files.write(Paths.get("/work/xxx.lmk"), lmkdata.getBytes()); 
    done.run();
});
```
- Matters need attention
  
  1. If the credential created by using Lmk mode is used, it needs to execute LoginConfig.setLmkUpdater to install the LmkUpdater object after creating the login object through LoginConfig.credentialLogin.
  
  2. For the security, LmkUpdater should be designed as LmkUpdater.update(LmkBundle lmkBundle). When the user stores the LmkBundle, it sets a password. In this way, it needs to use LmkBundle.save to reset the password, encrypt the LmkBundle and then perform the storage, which is usually difficult for users to accept. In actual implementation, the passphrase is uploaded to the server during the login process. If the LmkBundle needs to be updated, it is encrypted by the passphrase and pushed back to the client. So the LmkBundle.save method should be used sparingly to avoid conflicts.
  
  3. The server implementation guarantees the integrity of the LmkBundle update transaction, and the entire integrity of the guarantee must have the client's participation. Specifically, if Auany is detected that an updated LmkBundle has been stored during login, the LmkBundle is provided in the online notification returned by Switcher to the Endpoint. Upon receiving the online notification, the Endpoint immediately triggers LmkUpdater, after lmkdata saved run done, announce Auany to clear the stored LmkBundle.
  
  4. Refer to "PKIX Support", Location section, where scheme adds LMK type. Similar to PKCS12, java -jar limax.jar pkix copy <locationSRC> <locationDST> is used to perform format conversion. Non-RSA execution fails. In addition, in order to save space, the LmkBundle signed by the Lmk signing service does not include the root certificate, and conversion to other formats also fails.

7.13.3 Sign LmkBundle
- Design Principles
  
  1. The Limax framework provides Lmk signing service that supports the signing and recycling of LmkBundles.
  
  2. Large trird-party organizations that have the ability to deploy Lmk signing service can use their own LmkCA certificates to run signing service and distribute LmkBundle for their own users.
  
  3. The small and micro trird-party institution that has no the ability to deploy Lmk signing service can request its own client certificate, access the signing service running on the generic CA certificate, and issue LmkBundle for its own users.
- Create LmkCA
```
java -jar limax.jar pkix initlmkca <locationROOT> (<locationCA>|<keygen/.pub>) <subject> <domain> <yyyyMMdd> <yyyyMMdd> <OcspDomainOfRoot>
```
  The difference between using a ROOTCA certificate to sign a trird-party institution's LmkCA and the signing of a generic CA certificate (see PKIX Support) is a more domain parameter that is equivalent to the platform name in Auany's configuration, which allows using the same name as the platform name. This means that this third-party organization supports both the usual third-party login mode and the Lmk mode.
  
  For example:
```
java -jar limax.jar pkix initlmkca "file:ca@/work/pkix/root" "file:lmkca@/work/pkix/ca/#rsa/2048" "dc=lmkca,dc=limax-project,dc=org" "lmkca.limax-project.org" "20170101" "20300101" "root.limax-project.org"
```
- Sign Lmk service request certificate
  
  It should be noted that the dNSName here corresponding to platform name in Auany.

Prev Next

7.13 LimaxKey

7.13.1 Design essential

7.13.2 Client development (using the java client as example)

7.13.3 Sign LmkBundle