@@ -500,13 +500,16 @@ In Lime, the **client can receive and process commands requests** from other nod
500500
501501### Session
502502
503+ > The session establishment flow is automatically handled by the library.
504+ > This section is for informative purposes only.
505+
503506The session envelope is used for the negotiation, authentication and establishment of the communication channel between
504507the client and a server.
505- It helps select the transport options, like compression and encryption (TLS), authentication credentials, and session
506- metadata, like its ` id ` and local/remote node addresses.
508+ It helps the parties to select the transport options, like compression and encryption (TLS), authentication credentials,
509+ and session metadata, like its ` id ` and local/remote node addresses.
507510
508- For instance, the first envelope sent in every like session is the ** new session** envelope, which the client sends to
509- the server after the transport connection is established:
511+ The first envelope sent in every Lime session is the ** new session** envelope, which the client sends to the server
512+ after the transport connection is established:
510513
511514``` json
512515{
@@ -531,11 +534,88 @@ encryption by default).
531534
532535Note that this envelope haves a ` id ` defined, which is the ** session id** .
533536The next session envelopes sent by the client should use this same id, until the end of the session.
537+ During the session establishment, only session envelopes are allowed.
538+
539+ The server can skip the ` negotiating ` state and jump directly to the ` authenticating ` or even to the ` established `
540+ state. The session state progression can occur in the following order:
534541
535- The session state progression can occur in the following order:
536- 1 . new (client started)
542+ 1 . new (started by the client)
5375432 . negotiating (optional)
5385443 . authenticating (optional)
5395454 . established
540- 5 . finishing (optional, client started)
541- 6 . finished OR failed
546+ 5 . finishing (optional, started by the client)
547+ 6 . finished OR failed (final)
548+
549+ In Go, the session negotiation, authentication, and establishment process is ** automatically handled** by the
550+ ` lime.Client ` and ` lime.Server ` types.
551+ You just need to make sure that the server and client are configured accordingly the desired behavior.
552+
553+ For instance, if you want to ensure that the TCP transport connections are using the TLS encryption, you will need to
554+ configure the server similarly to this:
555+
556+ ``` go
557+ server := lime.NewServerBuilder ().
558+ // Enable the TLS encryption option for all sessions
559+ EncryptionOptions (lime.SessionEncryptionTLS ).
560+ // Set up the TCP listener providing a certificate
561+ ListenTCP (addr, &lime.TCPConfig {
562+ TLSConfig : &tls.Config {
563+ GetCertificate: func (info *tls.ClientHelloInfo ) (*tls.Certificate , error ) {
564+ cert , err := tls.LoadX509KeyPair (" cert.pem" " key.pem"
565+ if err != nil {
566+ return nil , err
567+ }
568+ return &cert, nil
569+ },
570+ }}).
571+ // TODO: Setup other server options
572+ Build ()
573+ ```
574+
575+ And in the client side, you should set up the TLS encryption option and the TCP config:
576+
577+ ``` go
578+ client := lime.NewClientBuilder ().
579+ Encryption (lime.SessionEncryptionTLS ).
580+ UseTCP (addr, &lime.TCPConfig {
581+ TLSConfig : &tls.Config {ServerName: " localhost"
582+ }).
583+ // TODO: Setup other client options
584+ Build ()
585+ ```
586+
587+ You may also want to configure the server and client authentication mechanisms.
588+ The Lime Go library supports the following schemes:
589+ - Guest (no authentication)
590+ - Plain (password)
591+ - Key
592+ - Transport (mutual TLS on TCP)
593+ - External (token emitted by an issuer)
594+
595+ To enable the use of plain authentication, in the server you should use the ` EnablePlainAuthentication ` method passing
596+ the authentication handler function, like in the example below:
597+
598+ ``` go
599+ server := lime.NewServerBuilder ().
600+ EnablePlainAuthentication (
601+ func (ctx context .Context , i lime .Identity , pwd string ) (*lime .AuthenticationResult , error ) {
602+ // TODO: implement checkCredentials to validate the user/password in your secret store
603+ if checkCredentials (i.Name , pwd) {
604+ return &lime.AuthenticationResult {Role: lime.DomainRoleMember }, nil
605+ }
606+ return &lime.AuthenticationResult {Role: lime.DomainRoleUnknown }, nil
607+ }).
608+ // TODO: Setup other server options
609+ Build ()
610+ ```
611+
612+ On the client side, you can use the ` PlainAuthentication ` method to set the password that should be used:
613+
614+ ``` go
615+ client := lime.NewClientBuilder ().
616+ // Sets the identity name and password
617+ Name (" john"
618+ PlainAuthentication (" mysecretpassword"
619+ // TODO: Setup other client options
620+ Build ()
621+ ```
0 commit comments