User Space Crypto API Interface

user space 인터페이스 소개

User Space 인터페이스

소개

kernel space에 공개되는 커널 Crypto API 개념은 user space 인터페이스에도 그대로 적용됩니다. 따라서 in-kernel 사용 사례에 관한 커널 Crypto API의 상위 수준 설명도 여기에 적용됩니다.

다만 가장 큰 차이는 user space가 consumer로만 동작할 수 있고 transformation 또는 cipher 알고리즘의 provider가 될 수 없다는 점입니다.

이 문서는 커널 Crypto API가 export하는 user space 인터페이스를 다룹니다. 설명대로 동작하는 예제는 [1]의 libkcapi에서 얻을 수 있으며, kernel의 암호화 서비스가 필요한 user space application에서 이 library를 사용할 수 있습니다.

in-kernel 커널 Crypto API의 일부 세부 사항은 user space에 적용되지 않습니다. synchronous 호출과 asynchronous 호출의 구분이 그 예이며, user space API 호출은 완전히 synchronous입니다.

[1] https://www.chronox.de/libkcapi.html

user space API 일반 사항

User Space API 일반 사항

커널 Crypto API는 user space에서 접근할 수 있습니다. 현재 다음 cipher를 사용할 수 있습니다.

• keyed message digest(HMAC, CMAC)를 포함한 message digest
• symmetric cipher
• AEAD cipher
• random number generator

인터페이스는 `AF_ALG` type의 socket으로 제공됩니다. `setsockopt` option type은 `SOL_ALG`입니다. user space header file이 아직 이 flag를 export하지 않는다면 다음 macro를 사용합니다.

#ifndef AF_ALG
#define AF_ALG 38
#endif
#ifndef SOL_ALG
#define SOL_ALG 279
#endif

cipher 이름과 socket 초기화

cipher는 in-kernel API 호출과 같은 이름으로 접근합니다. 여기에는 cipher의 generic 이름과 unique 이름 체계, generic 이름에 대한 priority 적용이 포함됩니다.

커널 Crypto API와 상호 작용하려면 user space application이 socket을 생성해야 합니다. user space는 `send()`/`write()` system call 계열로 cipher 연산을 요청하고 `read()`/`recv()` 계열로 연산 결과를 얻습니다.

아래 API 호출은 user space application이 socket descriptor를 이미 열었다고 가정하며, 커널 Crypto API에 특화된 호출만 설명합니다.

socket 인터페이스를 초기화하려면 consumer가 다음 순서를 수행해야 합니다.

• 아래 cipher type별 `struct sockaddr_alg` parameter를 지정해 `AF_ALG` type socket을 생성합니다.
• socket descriptor로 `bind`를 호출합니다.
• socket descriptor로 `accept`를 호출합니다. `accept`가 반환한 새 file descriptor는 특정 cipher instance와 상호 작용하는 데 사용합니다. kernel에 데이터를 보내는 `send`/`write` 또는 kernel에서 데이터를 받는 `recv`/`read` 호출에는 반드시 이 descriptor를 사용해야 합니다.

in-place cipher 연산

In-place cipher 연산

in-kernel 커널 Crypto API 연산과 마찬가지로 user space 인터페이스도 in-place cipher 연산을 허용합니다. 즉, `send`/`write`에 쓰는 입력 buffer와 `read`/`recv`에 쓰는 출력 buffer가 같아도 됩니다. 출력 데이터를 최종 목적지로 복사하는 작업을 피할 수 있어 symmetric cipher 연산에서 특히 유용합니다.

반대로 consumer가 plaintext와 ciphertext를 서로 다른 memory 위치에 유지하려면 encryption과 decryption 연산에 서로 다른 memory pointer를 제공하면 됩니다.

message digest API

Message Digest API

cipher 연산에 사용할 message digest type은 `bind` syscall을 호출할 때 선택합니다. `bind`에는 채워진 `struct sockaddr` data structure를 전달해야 하며 다음과 같이 구성합니다.

struct sockaddr_alg sa = {
    .salg_family = AF_ALG,
    .salg_type = "hash", /* this selects the hash logic in the kernel */
    .salg_name = "sha1" /* this is the cipher name */
};

`salg_type` 값 "hash"는 message digest와 keyed message digest에 적용됩니다. keyed message digest는 해당 `salg_name`으로 지정합니다. key 설정 방법은 아래 `setsockopt` 인터페이스 설명을 참조하십시오.

`send()` system call로 application이 message digest 처리 대상 데이터를 제공합니다. 다음 flag를 지정할 수 있습니다.

• `MSG_MORE`: 이 flag가 설정되면 `send`는 최종 hash를 아직 계산하지 않는 message digest update 함수처럼 동작합니다. 설정하지 않으면 `send`가 즉시 최종 message digest를 계산합니다.

`recv()` system call로 커널 Crypto API에서 message digest를 읽습니다. buffer가 message digest를 담기에 너무 작으면 kernel이 `MSG_TRUNC` flag를 설정합니다.

message digest key를 설정하려면 application이 `ALG_SET_KEY` 또는 `ALG_SET_KEY_BY_KEY_SERIAL` option으로 `setsockopt()`를 호출해야 합니다. key를 설정하지 않으면 key 때문에 발생하는 초기 HMAC state 변경 없이 HMAC 연산을 수행합니다.

symmetric cipher API

Symmetric Cipher API

연산은 message digest 방식과 매우 비슷합니다. 초기화할 때 `struct sockaddr` data structure를 다음과 같이 채웁니다.

struct sockaddr_alg sa = {
    .salg_family = AF_ALG,
    .salg_type = "skcipher", /* this selects the symmetric cipher */
    .salg_name = "cbc(aes)" /* this is the cipher name */
};

`write`/`send` system call 계열로 kernel에 데이터를 보내기 전에 consumer가 key를 설정해야 합니다. key 설정은 아래 `setsockopt` 호출에서 설명합니다.

`sendmsg()`로 encryption 또는 decryption할 데이터를 제공합니다. IV도 `sendmsg()`가 제공하는 data structure에 지정합니다.

`sendmsg` parameter인 `struct msghdr`는 `struct cmsghdr` data structure 안에 포함됩니다. `cmsghdr`를 `send`/`recv` 계열과 함께 사용하는 방법은 `recv(2)`와 `cmsg(3)`을 참조하십시오. 별도 header instance로 다음 정보를 담습니다.

• `ALG_OP_ENCRYPT`: data encryption을 지정하는 cipher 연산 flag
• `ALG_OP_DECRYPT`: data decryption을 지정하는 cipher 연산 flag
• `ALG_SET_IV`: IV 정보를 지정하는 flag

`send` system call 계열에는 다음 flag를 지정할 수 있습니다.

• `MSG_MORE`: 이 flag가 설정되면 이후 `send` 호출로 입력 데이터가 더 들어올 것을 기대하는 cipher update 함수처럼 동작합니다.

참고: 예상하지 않은 데이터가 들어오면 kernel은 `-EINVAL`을 보고합니다. caller는 모든 데이터가 선택한 cipher의 `/proc/crypto` 제약과 일치하도록 해야 합니다.

`recv()`로 커널 Crypto API에서 cipher 연산 결과를 읽습니다. 출력 buffer는 encrypt 또는 decrypt된 데이터의 모든 block을 담을 만큼 커야 합니다. 더 작으면 출력 buffer에 들어가는 block 수만큼만 반환합니다.

AEAD cipher 초기화

AEAD Cipher API

연산은 symmetric cipher 방식과 매우 비슷합니다. 초기화할 때 `struct sockaddr` data structure를 다음과 같이 채웁니다.

struct sockaddr_alg sa = {
    .salg_family = AF_ALG,
    .salg_type = "aead", /* this selects the symmetric cipher */
    .salg_name = "gcm(aes)" /* this is the cipher name */
};

`write`/`send` 계열로 kernel에 데이터를 보내기 전에 consumer가 key를 설정해야 합니다. key 설정은 아래 `setsockopt` 호출에서 설명합니다.

또한 데이터를 보내기 전에 authentication tag 크기를 설정해야 합니다. caller는 아래에서 설명하는 `setsockopt` 호출을 사용합니다.

AEAD 요청과 오류 처리

`sendmsg()`로 encryption 또는 decryption할 데이터를 제공하고, `sendmsg()`의 data structure에 IV를 지정합니다.

`sendmsg` parameter인 `struct msghdr`는 `struct cmsghdr` 안에 포함됩니다. 사용법은 `recv(2)`와 `cmsg(3)`을 참조하십시오. 별도 header instance로 다음 정보를 담습니다.

• `ALG_OP_ENCRYPT`: data encryption을 지정하는 cipher 연산 flag
• `ALG_OP_DECRYPT`: data decryption을 지정하는 cipher 연산 flag
• `ALG_SET_IV`: IV 정보를 지정하는 flag
• `ALG_SET_AEAD_ASSOCLEN`: associated authentication data(AAD)를 지정하는 flag. AAD는 plaintext 또는 ciphertext와 함께 kernel로 전송되며 memory 구조는 아래에서 설명합니다.

`send` system call 계열에는 다음 flag를 지정할 수 있습니다.

• `MSG_MORE`: 이 flag가 설정되면 이후 `send` 호출로 입력 데이터가 더 들어올 것을 기대하는 cipher update 함수처럼 동작합니다.

참고: 예상하지 않은 데이터가 들어오면 kernel은 `-EINVAL`을 보고합니다. caller는 모든 데이터가 선택한 cipher의 `/proc/crypto` 제약과 일치하도록 해야 합니다.

`recv()`로 커널 Crypto API에서 cipher 연산 결과를 읽습니다. 출력 buffer는 아래 memory structure에서 정의한 크기 이상이어야 하며, 더 작으면 cipher 연산을 수행하지 않습니다.

authenticated decryption 연산은 integrity error를 나타낼 수 있습니다. integrity가 깨지면 `-EBADMSG` error code로 표시합니다.

AEAD memory structure

AEAD Memory Structure

AEAD cipher는 user space와 kernel space 사이에서 하나의 data stream으로 전달되는 다음 정보를 사용합니다.

• plaintext 또는 ciphertext
• associated authentication data(AAD)
• authentication tag

AAD와 authentication tag의 크기는 `sendmsg` 및 `setsockopt` 호출로 제공합니다. kernel은 전체 data stream 크기를 알고 있으므로 각 구성 요소의 올바른 offset을 계산할 수 있습니다.

user space caller는 입력 정보를 다음 순서로 배치해야 합니다.

• AEAD encryption 입력: `AAD || plaintext`
• AEAD decryption 입력: `AAD || ciphertext || authentication tag`

caller가 제공하는 출력 buffer는 다음 데이터를 담을 만큼 커야 합니다.

• AEAD encryption 출력: `ciphertext || authentication tag`
• AEAD decryption 출력: `plaintext`

random number generator API

Random Number Generator API

다른 API와 마찬가지로 초기화할 때 `struct sockaddr` data structure를 다음과 같이 채웁니다.

struct sockaddr_alg sa = {
    .salg_family = AF_ALG,
    .salg_type = "rng", /* this selects the random number generator */
    .salg_name = "drbg_nopr_sha256" /* this is the RNG name */
};

RNG type에 따라 seed가 필요합니다. seed는 key를 설정하는 `setsockopt` 인터페이스로 제공합니다. 예를 들어 `ansi_cprng`에는 seed가 필요합니다. DRBG에는 seed가 필수는 아니지만 제공할 수 있습니다. NIST SP 800-90A 표준에서는 seed를 Personalization String이라고도 합니다.

`read()`/`recvmsg()`로 random number를 얻습니다. kernel은 한 번의 호출에서 최대 128 byte를 생성하므로 더 많은 데이터가 필요하면 여러 번 호출해야 합니다.

경고: user space caller는 앞서 설명한 `accept`를 여러 번 호출할 수 있습니다. 이 경우 반환된 file descriptor들은 동일한 state를 공유합니다.

RNG CAVP test 인터페이스

kernel을 `CRYPTO_USER_API_RNG_CAVP` option으로 build하면 다음 CAVP test 인터페이스가 활성화됩니다.

• Entropy와 Nonce를 이어 붙인 값을 `ALG_SET_DRBG_ENTROPY` setsockopt 인터페이스로 RNG에 제공할 수 있습니다. entropy 설정에는 `CAP_SYS_ADMIN` 권한이 필요합니다.
• Additional Data는 `send()`/`sendmsg()`로 제공할 수 있지만 entropy를 설정한 뒤에만 가능합니다.

zero-copy 인터페이스

Zero-Copy Interface

`send`/`write`/`read`/`recv` 계열뿐 아니라 `splice`/`vmsplice`의 zero-copy 인터페이스로도 `AF_ALG`에 접근할 수 있습니다. 이름처럼 kernel은 kernel space로의 copy 연산을 피하려고 합니다.

zero-copy 연산은 data가 page boundary에 정렬되어 있어야 합니다. 정렬되지 않은 데이터도 사용할 수 있지만 kernel 연산이 늘어나 zero-copy로 얻은 성능 이점이 사라질 수 있습니다.

한 번의 zero-copy 연산에 적용되는 system 고유 크기 제한은 16 page입니다. 더 많은 데이터를 `AF_ALG`에 보내려면 user space가 입력을 최대 16 page 크기의 segment로 나눠야 합니다.

다음은 zero-copy 사용 예제이며, 완전히 동작하는 예제는 libkcapi에서 제공합니다.

int pipes[2];

pipe(pipes);
/* input data in iov */
vmsplice(pipes[1], iov, iovlen, SPLICE_F_GIFT);
/* opfd is the file descriptor returned from accept() system call */
splice(pipes[0], NULL, opfd, NULL, ret, 0);
read(opfd, out, outlen);

setsockopt 인터페이스

Setsockopt Interface

consumer는 cipher 연산 대상 데이터를 보내고 받는 `read`/`recv` 및 `send`/`write` 처리 외에도 연산에 필요한 추가 정보를 설정해야 합니다. 이 정보는 열린 cipher의 file descriptor, 즉 `accept`가 반환한 descriptor로 `setsockopt`를 호출해 설정합니다.

모든 `setsockopt` 호출은 level로 `SOL_ALG`를 사용해야 합니다.

`setsockopt` 인터페이스는 다음 optname으로 데이터를 설정합니다.

• `ALG_SET_KEY`: key를 설정합니다. skcipher(symmetric cipher), hash(keyed message digest), AEAD, seed를 제공하는 RNG cipher type에 적용됩니다.
• `ALG_SET_KEY_BY_KEY_SERIAL`: keyring의 `key_serial_t`를 통해 key를 설정하며 `ALG_SET_KEY`와 동일하게 동작합니다. keyring key에서 복호화한 데이터를 복사해 symmetric encryption key로 사용합니다.
• `ALG_SET_KEY_BY_KEY_SERIAL`에 전달한 `key_serial_t`에는 `KEY_(POS|USR|GRP|OTH)_SEARCH` 권한이 있어야 하며, 없으면 `-EPERM`을 반환합니다. user, logon, encrypted, trusted key type을 지원합니다.
• `ALG_SET_AEAD_AUTHSIZE`: AEAD cipher의 authentication tag 크기를 설정합니다. encryption은 지정한 크기의 tag를 생성하고, decryption은 제공된 ciphertext에 그 크기의 tag가 포함되었다고 가정합니다.
• `ALG_SET_DRBG_ENTROPY`: random number generator의 entropy를 설정하며 RNG cipher type에만 적용됩니다.

user space API 예제

User space API 예제

[1]의 libkcapi는 앞서 설명한 Netlink kernel 인터페이스를 쉽게 사용할 수 있게 감싸는 wrapper입니다. 같은 위치에 모든 libkcapi API 호출을 실행하는 test application도 있습니다.

[1] https://www.chronox.de/libkcapi.html