libradius

명칭
     libradius — RADIUS 클라이언트 프로그램 라이브러리

서식
     <radlib.h> struct rad_handle * rad_acct_open(void) int
     rad_add_server(struct rad_handle *h, const char *host, int port, const char
     *secret, int timeout, int max_tries) struct rad_handle *
     rad_auth_open(void) void rad_close(struct rad_handle *h) int
     rad_config(struct rad_handle *h, const char *file) int
     rad_continue_send_request(struct rad_handle *h, int selected, int *fd,
     struct timeval *tv) int rad_create_request(struct rad_handle *h, int code)
     struct in_addr rad_cvt_addr(const void *data) u_int32_t rad_cvt_int(const
     void *data) char * rad_cvt_string(const void *data, size_t len) int
     rad_get_attr(struct rad_handle *h, const void **data, size_t *len) int
     rad_init_send_request(struct rad_handle *h, int *fd, struct timeval *tv)
     int rad_put_addr(struct rad_handle *h, int type, struct in_addr addr) int
     rad_put_attr(struct rad_handle *h, int type, const void *data, size_t len)
     int rad_put_int(struct rad_handle *h, int type, u_int32_t value) int
     rad_put_string(struct rad_handle *h, int type, const char *str) int
     rad_send_request(struct rad_handle *h) const char * rad_strerror(struct
     rad_handle *h)

해설
     libradius 프로그램 라이브러리는, 유저 서비스 원격 인증 다이얼 (RADIUS)의 클라이언트측을 실장하고 있습니다.
     RADIUS 는 및 그리고 정의되고 있어 클라이언트는 리모트 인증 서버에의 네트워크 요구에 의해 인증과 어카운팅을 받을 수가 있습니다.

초기설정
     프로그램 라이브러리를 사용하는 경우에 어플리케이션은, 우선 rad_auth_open() 인가 rad_acct_open() (을)를
     호출해, 다음의 조작을 위한 문맥을 준다 struct rad_handle * (을)를 취득합니다.  전자는 RADIUS 인증에 사용되어
     후자는 RADIUS 어카운팅에 사용됩니다.  rad_auth_open() 및 rad_acct_open() 의 호출은, 가상 메모리가
     부족한 경우를 제외해, 항상 정상 종료합니다.  필요한 메모리를 할당할 수 없을 때, 함수는 NULL (을)를 돌려줍니다.  이전의
     버젼의 본프로그램 라이브러리와의 호환성을 위해서(때문에), rad_open() 하지만 rad_auth_open() 의 동의어로서
     제공되고 있습니다.

     RADIUS 에의 요구를 내기 전에, 프로그램 라이브러리는 컨택트 가능한 서버를 확인하지 않으면 안됩니다. 프로그램 라이브러리의 설정을
     하는 가장 간단한 방법은 rad_config() (을)를 호출하는 것입니다.  rad_config() 에 의해, 프로그램 라이브러리는
     radius.conf(5) 그리고 포맷이 정의되고 있는 configuration file를 읽어들입니다.  configuration
     file의 패스명은 인수 file (으)로서 rad_config() 에 건네받습니다. 이 인수에는 NULL 하지만 지정되어도
     괜찮습니다. 그 경우는 표준 configuration file /etc/radius.conf 하지만 사용됩니다.
     rad_config() (은)는, 정상 종료시에는 0 을 돌려주어, 에러 종료시에는 -1 을 돌려줍니다.

     프로그램 라이브러리는 rad_add_server() (을)를 호출하는 것에 의해, 정해진 순서로 설정할 수도 있습니다. 파라미터
     host 파라미터는, 서버 호스트를 지정해, 완전한 도메인명 (FQDN)에서도, 또는 닷 단락의 네 개의 숫자로 텍스트 형식 그리고
     쓰여진 IP 주소의 어디에서 지정해도 괜찮습니다.  파라미터 port (은)는, 서버에 접속할 때의 UDP 포트 번호를 지정합니다.
     port 의 지정이 0 때, 프로그램 라이브러리는 네트워크 서비스 데이타베이스의 ‘radius/udp’ 또는 ‘radacct/udp’
     서비스를 검색해, 발견된 포트를 사용합니다.  엔트리가 발견되지 않을 때에는, 프로그램 라이브러리는 표준 RADIUS 포트, 즉
     인증에는 1812 를 어카운팅에는 1813 을 사용합니다.  서버 호스트에 관한 공유 비밀 정보는, 파라미터 secret (으)로서
     건네받습니다. 파라미터는 NUL 그리고 종료하는 어떤 캐릭터 라인도 괜찮습니다.  RADIUS 프로토콜에서는, 공유 비밀 정보의 128
     바이트부터 후는 무시됩니다. 서버로부터의 수신 타임 아웃은, 파라미터 timeout 에 의해, 초의 단위로 건네받습니다. 요구를 포기할
     때까지의 최대 반복 회수는, 파라미터 max_tries 그리고 건네받습니다.  rad_add_server() 하 정상 종료 때는 0 을
     돌려주어, 에러가 발생했을 때는 -1 을 돌려줍니다.

     rad_add_server() (은)는, 여러 차례 호출이 가능해, rad_config() (와)과 함께 사용할 수가 있습니다.
     서버는, 10 개까지 지정할 수 있습니다. 복수 서버가 지정되었을 경우, 올바른 응답을 얻을 수 있는지, 또는 서버의 max_tries
     제한에 이를 때까지, 라운드로빈 방식에서 호출을 시도합니다.

RADIUS 요구의 생성
     RADIUS 요구는, 요구의 종류를 지정하는 코드와 제로 혹은 부가 정보를 주는 복수의 속성치로 구성됩니다. 신규 요구의 작성은, 우선
     rad_create_request() 호출로부터 시작합니다. 통상의 struct rad_handle * 에 가세해, 이 함수는,
     파라미터 code (을)를 취해, 그것에 의해 요구 타입을 지정합니다. 대체로 RAD_ACCESS_REQUEST 하지만 지정됩니다.
     rad_create_request() (은)는 정상 종료 때는 0 을 돌려주어, 에러가 발생했을 때는 -1 을 돌려줍니다.

     rad_create_request() 에 의해 요구가 생성된 후, 속성을 부가할 수가 있습니다. 이것은, rad_put_addr(),
     rad_put_int(), rad_put_string() 호출에 의해 행해집니다. 이것들은, 속성을 결정하는 파라미터 type
     (이)나, 인터넷 주소치, 정수치, NUL 그리고 종료하는 캐릭터 라인을, 각각 받습니다.

     프로그램 라이브러리에는, 함수 rad_put_attr() 도 갖춰지고 있으므로, 미가공으로 해석할 수 없는 속성도 줄 수가 있습니다.
     인수 data (은)는, 바이트 배열의 선두의 포인터로, 인수 len (은)는, 그 길이를 지정합니다.

     함수 rad_put_X() (은)는, 정상 종료시에는 0 돌려주어, 에러 발생시에는 -1 을 돌려줍니다.

요구의 송신과 응답의 수신
     RADIUS 요구는 생성된 후, rad_send_request() 또는 rad_init_send_request() (와)과
     rad_continue_send_request() 호출의 조 맞댐에 의해, 송신됩니다.

     함수 rad_send_request() (은)는, 요구를 송신해, 필요하면 정의된 서버에 대해서 라운드로빈 방식에서 접속을 시도해
     올바른 응답이를 기다립니다.  올바른 응답이 있었을 경우, rad_send_request() (은)는 응답의 타입을 지정하는
     RADIUS 코드를 돌려줍니다.  반환값은, 일반적으로 RAD_ACCESS_ACCEPT, RAD_ACCESS_REJECT,
     RAD_ACCESS_CHALLENGE 입니다. 올바르지 않은 응답을 수신했을 때, rad_send_request() (은)는 -1 을
     돌려줍니다.

     응답 대기를 블록 하고 싶지 않은 경우는, 대신에 rad_init_send_request() 및
     rad_continue_send_request() (을)를 사용할 수 있습니다.  RADIUS 서버로부터의 대답을 수신하는지, 또는
     타임 아웃이 되었을 경우, 이러한 함수는 rad_send_request() 의 항으로 든 값을 돌려줍니다. 그 이외에서는, 제로가
     돌려주어 fd tv 에서의 가리키는 값이 select(2) 에게 건네지는 디스크립터와 타임 아웃으로 설정됩니다.

     rad_init_send_request() (은)는 최초로 호출할 필요가 있어, 계속되어, 반환값이 0 이 아니게 될 때까지
     rad_continue_send_request() 호출을 반복합니다.  각각의 호출동안에, 어플리케이션은, select(2) (을)를
     호출할 필요가 있어, 그 때 *fd (을)를 읽기 디스크립터로서 건네주어, tv 그리고 정의되는 시간 경과의 뒤, 타임 아웃 합니다.
     select 로부터 제어가 돌아왔을 때, select(2) 그리고 디스크립터가 읽어내 가능한 경우는, 인수 selected 에 0 이
     아닌 값을 설정해 rad_continue_send_request() (을)를 호출할 필요가 있습니다.

     RADIUS 에의 요구와 같이, 각 응답은 0 또는, 그 이상의 속성을 가지고 있습니다. 응답이 rad_send_request() 또는
     rad_continue_send_request() 에 의해 정상적으로 수신된 후, 속성은 rad_get_attr() 에 의해, 1
     개(살)씩 꺼낼 수가 있습니다.  rad_get_attr() 호출이 불릴 때마다, 현재의 응답으로부터 다음의 속성을 취득해, 참조
     파라미터 data len (을)를 개입시켜, 데이터에의 포인터와 데이터 길이를 각각 보관합니다.  데이터는 응답 그것 자신중에
     존재해, 변경해선 안 된다고 하는 것에 주의해 주세요.  rad_get_attr() 호출은, 정상 종료하면(자) RADIUS 속성
     타입을 돌려줍니다.  현재의 응답내에 속성이 없어지면(자)

     rad_get_attr() (은)는 0 을 돌려줍니다. 부정한 속성과 같은 에러가 검출되면(자), -1 (을)를 돌려줍니다.

     속성의 공통 타입은, rad_cvt_addr(), rad_cvt_int(), rad_cvt_string() 에 의해 디코드할 수가
     있습니다. 이러한 함수는, rad_get_attr() 에 의해 취득되는 속성 데이터에의 포인터를 받습니다.
     rad_cvt_string() 의 경우는, len 그리고 길이도 지정할 필요가 있습니다. 이러한 함수는, 속성을 인터넷 주소나 정수치,
     캐릭터 라인등으로 해서 해석해, 얻을 수 있던 값을 반환값으로서 돌려줍니다.  rad_cvt_string() (은)는 메모리를 동적으로
     할당해 NULL 그리고 종료한 캐릭터 라인을 돌려줍니다. 어플리케이션은, 불필요한 캐릭터 라인을 free(3) (을)를 사용해 해방하지
     않으면 안됩니다.

     충분한 가상 메모리가 없는 경우, rad_cvt_string() 하 NULL (을)를 돌려줍니다.  rad_cvt_addr() 및
     rad_cvt_int() 하지만 에러 종료할 것은 없습니다.

에러 메세지 취득
     인수 struct rad_handle * (을)를 받는 함수는, 이상종료(ABEND)의 경우에 에러 메세지를 기록합니다.  이 에러
     메세지는 rad_strerror() 호출로 꺼낼 수가 있습니다. 메세지 텍스트는, 얻을 수 있었다 struct rad_handle *
     에 의해, 새로운 에러로 덧쓰기됩니다.  그 때문에, 메세지를 보존해 두어야 하는 것이라면, 동일한 핸들을 사용해 계속 프로그램
     라이브러리 호출을 실시하는 것으로, 복사해 두지 않으면 안됩니다.

클린 업
     RADIUS 프로그램 라이브러리로 사용한 리소스는, rad_close() (을)를 호출로 해방할 수 있습니다.

반환값
     이하의 함수는, 처리가 정상적으로 종료시, 부가 아닌 값을 돌려줍니다. 에러를 검출했을 때는, -1 (을)를 돌려주어,
     rad_strerror() (을)를 사용해 꺼냈다 에러 메세지를 기록합니다.

           rad_add_server()
           rad_config()
           rad_create_request()
           rad_get_attr()
           rad_put_addr()
           rad_put_attr()
           rad_put_int()
           rad_put_string()
           rad_init_send_request()
           rad_continue_send_request()
           rad_send_request()

     이하의 함수는, 처리가 정상적으로 종료했을 때, NULL (이)가 아닌 포인터를 돌려줍니다.  충분한 가상 메모리의 할당을 할 수 없을
     때, NULL (을)를 돌려줍니다만, 에러 메세지는 기록되지 않습니다.

           rad_acct_open()
           rad_auth_open()
           rad_cvt_string()

관련 파일
     /etc/radius.conf

관련 항목
     radius.conf(5) C. Rigney, et al, Remote Authentication Dial In User Service
     (RADIUS), RFC 2138.  C. Rigney, RADIUS Accounting, RFC 2139.

저자
     이 소프트웨어는 원래 John Polstra 하지만 기술해, Juniper Networks, Inc 가 FreeBSD 프로젝트에
     기증했습니다.  그 후 Oleg Semyonov 하지만 RADIUS 어카운팅의 기능을 추가했습니다.