TRUNG TÂM AN NINH MẠNG VIETTEL

Thư viện Netty

TÀI LIỆU HƯỚNG DẪN SỬ DỤNG

Tên tài liệu: HDSD_Netty_v1.0

Hà Nội, tháng 07 năm 2015

Tài liệu Hướng dẫn sử dụng v1.0

BẢNG GHI NHẬN THAY ĐỔI TÀI LIỆU

*A – Tạo mới, M – Sửa đổi, D – Xóa bỏ
Ngày Vị trí A* Nguồn gốc Phiên Mô tả thay đổi Phiên
thay đổi thay đổi M, D bản cũ bản mới
15/07/2015 A* Tạo mới 1.0

1/19
Tài liệu Hướng dẫn sử dụng v1.0

TRANG KÝ

Người lập: Phạm Văn Tân Ngày: 15/07/2015

Trưởng ban

Người xem xét: Đinh Hữu Công Ngày:

Trưởng phòng

Người phê duyệt: Nguyễn Sơn Hải Ngày:

Giám đốc

2/19
Tài liệu Hướng dẫn sử dụng v1.0

BẢNG THUẬT NGỮ VÀ TỪ VIẾT TẮT

STT Thuật ngữ Định nghĩa Ghi chú

3/19
Tài liệu Hướng dẫn sử dụng v1.0

MỤC LỤC

BẢNG THUẬT NGỮ VÀ TỪ VIẾT TẮT..................................................................................................3

1. GIỚI THIỆU CHUNG.........................................................................................................................5
2. MÔ TẢ CHUNG.................................................................................................................................6
3. HƯỚNG DẪN CÀI ĐẶT....................................................................................................................7
3.1 Môi trường lập trình.....................................................................................................................7
3.2 Thư viện sử dụng.........................................................................................................................7
4. Giao thức client-server........................................................................................................................9
5. Mô hình chi tiết server example.........................................................................................................10
5.1 Cấu trúc thư mục.......................................................................................................................10
5.2 Class ServerFactory...................................................................................................................10
5.3 Class ServerHandler..................................................................................................................11
5.4 Class ServerInitializer................................................................................................................11
5.5 Class ServerContext...................................................................................................................11
5.6 Class ServerKeyManager...........................................................................................................12
6. Mô hình chi tiết CLIENT example....................................................................................................13
6.1 Cấu trúc thư mục.......................................................................................................................13
6.2 Class ClientFactory....................................................................................................................14
6.3 Class ClientHandler...................................................................................................................14
6.4 Class ClientInitializer................................................................................................................14
6.5 Class ClientContext...................................................................................................................15
6.6 Class ClientKeyManager...........................................................................................................15
7. PHỤ LỤC..........................................................................................................................................16
8. Tài liệu tham khảo.............................................................................................................................17

4/19
Tài liệu Hướng dẫn sử dụng v1.0

1. GIỚI THIỆU CHUNG

Tài liệu này nhằm mục đích giới thiệu và hướng dẫn lập trình xây dựng một hệ thống
client-server sử dụng thư viện Netty:
- Hướng dẫn cài đặt các thư viện yêu cầu.
- Mô hình chi tiết Server.
- Mô hình chi tiết Client.
Tài liệu này được sử dụng kèm với tài liệu “Mô tả công nghệ” và source code ví dụ.

5/19
Tài liệu Hướng dẫn sử dụng v1.0

2. MÔ TẢ CHUNG
Ví dụ trong tài liệu này thực hiện xây dựng hệ thống Client và Server sử dụng thư viện
Netty sử dụng Google Protobuf, xác thực bằng SSL hai chiều. Giao thức client và server bao
gồm hai loại bản tin là login và ping. Có thể bổ sung thêm các loại bản tin vào giao thức tùy theo
nhu cầu thực tế. Hệ thống client, server này có các đặc điểm sau:
- Giữ kết nối
- Sử dụng Google Protocol Buffer
- Xác thực và mã hóa kênh truyền bằng SSL 2 chiều
- Cả Client và Server đều sử dụng mô hình Event-Driven

6/19
Tài liệu Hướng dẫn sử dụng v1.0

3. HƯỚNG DẪN CÀI ĐẶT

3.1 Môi trường lập trình

 Môi trường dev:
- Hệ điều hành Windows, Linux
- Java 1.7
- IDE: Eclipse J2EE
- Maven

3.2 Thư viện sử dụng

Hệ thống (cả client-example và server-example) đều sử dụng các thư viện sau (khai báo
trong dependency maven ở file pom.xml)
<dependencies>
<dependency>
<groupId>io.netty</groupId>
<artifactId>netty-buffer</artifactId>
<version>4.0.17.Final</version>
</dependency>
<dependency>
<groupId>io.netty</groupId>
<artifactId>netty-codec</artifactId>
<version>4.0.17.Final</version>
</dependency>
<dependency>
<groupId>io.netty</groupId>
<artifactId>netty-common</artifactId>
<version>4.0.17.Final</version>
</dependency>
<dependency>
<groupId>io.netty</groupId>
<artifactId>netty-handler</artifactId>
<version>4.0.17.Final</version>
</dependency>

7/19
Tài liệu Hướng dẫn sử dụng v1.0

<dependency>
<groupId>io.netty</groupId>
<artifactId>netty-transport</artifactId>
<version>4.0.17.Final</version>
</dependency>
<dependency>
<groupId>commons-io</groupId>
<artifactId>commons-io</artifactId>
<version>2.4</version>
</dependency>
<dependency>
<groupId>commons-codec</groupId>
<artifactId>commons-codec</artifactId>
<version>1.9</version>
</dependency>
<dependency>
<groupId>com.google.protobuf</groupId>
<artifactId>protobuf-java</artifactId>
<version>2.5.0</version>
</dependency>

8/19
Tài liệu Hướng dẫn sử dụng v1.0

4. GIAO THỨC CLIENT-SERVER

Giao thức Client-Server sử dụng Google Protobuf như sau:
enum MessageType {
LOGIN = 0;
PING = 1;
}

message LoginRequest {
optional string client_id = 1;
}

message LoginResponse {
enum LoginStatus {
SUCCESS = 0;
FAILTURE = 1;
}
optional LoginStatus login_status = 1;
}

message PingRequest {

message PingResponse {
optional int64 time_recv = 1;
}

// message ma client gui va server nhan duoc

message Server {
required MessageType message_type = 1;
optional LoginRequest login_request = 2;
optional PingRequest ping_request = 3;
}

//message ma server gui va client nhan duoc

message Client {
required MessageType message_type = 1;
optional LoginResponse login_response = 2;
optional PingResponse ping_response = 3;
}

Có 2 loại message chính là Client và Server. Trong đó message Server là các message mà Client
gửi tới Server tức outbound của Client và inbound của Server. Ngược lại message Client là các
message mà Server gửi trả về Client tức inbound của Client và outbound của Server. Mỗi
message có trường bắt buộc là MessageType, tùy theo giá trị của MessageType mà message
chứa các message con tương ứng của Login (LoginRequest, LoginResponse), Ping (PingRequest,
PingResponse). Mô hình thiết kế này đảm bảo tính mở rộng các message tùy theo nhu cầu thực
tế trong tương lai.

9/19
Tài liệu Hướng dẫn sử dụng v1.0

5. MÔ HÌNH CHI TIẾT SERVER EXAMPLE

5.1 Cấu trúc thư mục

Cấu trúc thư mục của một ứng dụng server-example như sau:
Package Class / file Mô tả
org.viettel.netty. ServerExample.java Class Main
serverexample
org.viettel.netty. ExampleProtocol.java File java do protobuf tự sinh ra
serverexample.protocols dựa trên file
ExampleProtocol.proto
org.viettel.netty. ExampleProtocol.proto File protocol mô tả giao thức
serverexample.protocols client, server

org.viettel.netty. ServerFactory.java Khởi chạy server listen trên

serverexample.server một port

org.viettel.netty. ServerHandler.java Xử lý khi server nhận được kết

serverexample.server
org.viettel.netty.
serverexample.server
nối thành công từ client và
handler khi nhận được các
message từ client.
ServerInitializer.java Cấu hình khởi tạo ssl và
ChannelPipeline

org.viettel.netty. ServerContext.java Kiểm tra ClientCertificate hợp

serverexample.ssl lệ

org.viettel.netty. ServerKeyManager.java Khởi tạo ServerKey

serverexample.server

5.2 Class ServerFactory

Class ServerFactory thực hiện khởi tạo ServerSocketChannel với các tham số boss threads,
worker threads. Nó thực hiện start server và listen trên một port. Mặc định không cần khởi tạo số
thread cho boss thread và worker thread. Số lượng các boss thread và worker thread được lấy tự
động theo số lượng core của CPU.

5.3 Class ServerHandler

 Class ServerHandler được extends từ SimpleChannelInboundHandler có nghĩa là nó sử
lý handler cho các request tới server theo chiều inbound. Chú ý trong khai báo extends

10/19
Tài liệu Hướng dẫn sử dụng v1.0

cần chỉ rõ message mà nó nhận được từ client (message ExampleProtocol.Server), các

event sau khi đi qua Handler ProtobufDecoder sẽ được decode thành Object
ExampleProtocol.Server
 Hàm callback channelActive được gọi khi kết nối, bắt tay thành công giữa client và
server
 Hàm callback channelRead0 được gọi khi server nhận được dữ liệu từ client, dữ liệu
này được decode thành một message ExampleProtocol.Server.

5.4 Class ServerInitializer

ServerInitializer thực hiện khởi tạo ChannelPipeline và thêm lần lượt các pipeline vào để
xử lý lần lượt như sau:
p.addLast("ssl", new SslHandler(engine));
p.addLast("frameDecoder", new ProtobufVarint32FrameDecoder());
p.addLast("protobufDecoder", new
ProtobufDecoder(ExampleProtocol.Server.getDefaultInstance()));

p.addLast("frameEncoder", new
ProtobufVarint32LengthFieldPrepender());
p.addLast("protobufEncoder", new ProtobufEncoder());

p.addLast("handler", new ServerHandler());

5.5 Class ServerContext

ServerContext thực hiện kiểm tra ClientCertificate bao gồm:

- Kiểm tra certificate còn thời gian hợp lệ
- Lấy thông tin clientID trong certificate từ trường SERIALNUMBER trong CN
- Kiểm tra certificate được ký bởi CARoot và chưa bị revoke

5.6 Class ServerKeyManager

Class ServerKeyManager thực hiện đọc server key từ file cấu hình. File server key là file
Java JKS, được bảo vệ bằng passphrase.

11/19
Tài liệu Hướng dẫn sử dụng v1.0

12/19
Tài liệu Hướng dẫn sử dụng v1.0

6. MÔ HÌNH CHI TIẾT CLIENT EXAMPLE

6.1 Cấu trúc thư mục

Cấu trúc thư mục của một ứng dụng client-example như sau:
Package Class / file Mô tả
org.viettel.netty. ClientExample.java Class Main
clientexample
org.viettel.netty. ExampleProtocol.java File java do protobuf tự sinh
clientexample.protocols ra dựa trên file
ExampleProtocol.proto
org.viettel.netty. ExampleProtocol.proto File protocol mô tả giao thức
clientexample.protocols client, server

org.viettel.netty. ClientFactory.java Khởi chạy kết nối tới một

clientexample.client
org.viettel.netty.
clientexample.client
ClientHandler.java
server, sau khi kết nối thành
công tự động gửi bản tin đầu
tiên là bản tin login, sau đó
tiến hành định kỳ ping
Xử lý khi client khi nhận
được các message từ server.

org.viettel.netty. ClientInitializer.java Cấu hình khởi tạo ssl và

clientexample.client ChannelPipeline

org.viettel.netty. WatchdogConnection.java Watchdog Connection kết nối

clientexample.client tới Server

org.viettel.netty. PingScheduler.java Định kỳ gửi bản tin Ping tới

clientexample.scheduler Server

org.viettel.netty. ServerContext.java Kiểm tra ServerCertificate

clientexample.ssl hợp lệ

org.viettel.netty. ClientKeyManager.java Khởi tạo ClientKey

clientexample.server

6.2 Class ClientFactory

Class ClientFactory thực hiện khởi tạo SocketChannel kết nối tới Server. Sau khi kết nối,
nó gửi bản tin đầu tiên tới server là bản tin Login. Nếu login thành công, Client định kỳ gửi bản

13/19
Tài liệu Hướng dẫn sử dụng v1.0

tin Ping tới Server. Nếu login không thành công, kết nối bị đóng và chờ Watchdog tiếp tục gọi
kết nối tới Server.

6.3 Class ClientHandler

 Class ServerHandler được extends từ SimpleChannelInboundHandler có nghĩa là nó sử
lý handler cho các request tới client theo chiều inbound. Chú ý trong khai báo extends
cần chỉ rõ message mà nó nhận được từ client (message ExampleProtocol.Client), các
event sau khi đi qua Handler ProtobufDecoder sẽ được decode thành Object
ExampleProtocol.Client
 Hàm login thực hiện gửi bản tin login tới Server. Do hệ thống toàn bộ được xử lý theo
asynchronous nên để cần loop trên một BlockingQueue để chờ bản tin LoginResponse
từ Server.
 Hàm callback channelRead0 được gọi khi client nhận được dữ liệu từ server, dữ liệu
này được decode thành một message ExampleProtocol.Client để xử lý.

6.4 Class ClientInitializer

ClientInitializer thực hiện khởi tạo ChannelPipeline và thêm lần lượt các pipeline vào để
xử lý lần lượt như sau:
p.addLast("ssl", new SslHandler(engine));
p.addLast("frameDecoder", new ProtobufVarint32FrameDecoder());
p.addLast("protobufDecoder", new
ProtobufDecoder(ExampleProtocol.Client.getDefaultInstance()));

p.addLast("frameEncoder", new
ProtobufVarint32LengthFieldPrepender());
p.addLast("protobufEncoder", new ProtobufEncoder());

p.addLast("handler", new ClientHandler());

6.5 Class ClientContext

ClientContext thực hiện kiểm tra ServerCertificate bao gồm:

- Kiểm tra certificate còn thời gian hợp lệ

14/19
Tài liệu Hướng dẫn sử dụng v1.0

- Lấy thông tin server trong certificate từ trường SERIALNUMBER trong CN

- Kiểm tra certificate được ký bởi CARoot và chưa bị revoke

6.6 Class ClientKeyManager

Class ClientKeyManager thực hiện đọc client key từ file cấu hình. File server key là file
Java JKS, được bảo vệ bằng passphrase.

15/19
Tài liệu Hướng dẫn sử dụng v1.0

7. PHỤ LỤC
N/A

16/19
Tài liệu Hướng dẫn sử dụng v1.0

8. TÀI LIỆU THAM KHẢO

STT Tài liệu tham khảo Mô tả/ Nguồn/ Đường dẫn nơi lưu trữ tài liệu
tham khảo

17/19