암호화 프레임워크 (Crypto API)

Linux Crypto Framework(Crypto API)를 커널 암호 연산의 공통 추상화 계층으로 심층 분석합니다. skcipher/aead/hash/rng API 분류와 사용 패턴, synchronous vs asynchronous 요청 경로, 비대칭 암호와 공개키 연산, AEAD 인증 암호화, 커널 난수 생성기, AF_ALG 사용자 공간 인터페이스를 다룹니다. 하드웨어 가속은 암호화 하드웨어 가속, 드라이버 구현은 암호화 드라이버 구현 가이드에서 별도로 다룹니다.

Linux Crypto Framework 개요

Linux 커널의 Crypto Framework(Crypto API)는 암호화 알고리즘을 커널 내에서 사용할 수 있도록 하는 통합 프레임워크입니다. 소프트웨어 구현과 하드웨어 가속(AES-NI, ARM CE, QAT, CAAM, CPT 등)을 동일한 인터페이스로 제공하여, 알고리즘 사용자(IPsec, dm-crypt, kTLS 등)가 구현 방식을 신경 쓰지 않아도 됩니다.

어디에서 사용되는가

Linux Crypto Framework 아키텍처 원리

Crypto Framework (Crypto API)는 알고리즘 구현과 사용을 분리하는 프레임워크 패턴으로 설계되어 있습니다. 핵심 개념은 세 가지입니다:

• Algorithm (알고리즘 등록): 각 암호화 구현체(SW 또는 HW)가 crypto_register_alg()으로 자신을 등록합니다. 같은 알고리즘의 여러 구현이 공존하며, priority 값으로 우선순위를 매깁니다.
• Transform (tfm): 사용자가 crypto_alloc_skcipher("cbc(aes)", ...)를 호출하면, 커널이 priority가 가장 높은 구현을 선택하여 인스턴스(tfm)를 생성합니다. 키를 설정하면 이 tfm으로 반복 암호화가 가능합니다.
• Request: 실제 데이터 처리 단위. scatterlist(물리 메모리(Physical Memory) 분산 목록)로 데이터를 전달하여 DMA 친화적인 zero-copy 처리가 가능합니다.

알고리즘 조합 (Template) 원리

Crypto Framework (Crypto API)의 강력한 특성 중 하나는 템플릿 기반 알고리즘 조합입니다. "cbc(aes)"에서 cbc는 운용 모드 템플릿이고 aes는 기본 블록 암호입니다. 커널은 이를 재귀적으로 해석하여:

Crypto API 소스 디렉토리 구조

Crypto Framework의 소스 코드는 커널 트리에서 명확하게 구역화되어 있습니다. 코드를 읽을 때 "어디서 무엇을 찾아야 하는지" 아는 것이 첫걸음입니다:

알고리즘 유형

Crypto API는 8가지 알고리즘 유형을 지원하며, 각각 전용 API와 전용 request 구조체를 가집니다. 목적에 맞는 유형을 선택하는 것이 첫 번째 설계 결정입니다:

비대칭 암호와 공개키 연산

커널 Crypto Framework에서 비대칭 연산은 하나의 API로 뭉뚱그리지 않고 암/복호화, 서명/검증, 키 합의를 각각 다른 인터페이스로 분리합니다. 이 구분을 이해하지 못하면 RSA, ECDSA, ECDH를 같은 계층의 대체재처럼 오해하게 됩니다.

중요한 차이: crypto_akcipher는 공개키로 암호화하고 개인키로 복호화하는 경로를 다루며, crypto_sig는 서명과 검증을 위해 별도 API를 사용합니다. crypto_kpp는 암/복호화가 아니라 양측이 동일한 공유 비밀을 계산하는 용도이므로, 의미상 완전히 다른 계층입니다.

RSA AKCIPHER 예제

공개키 암호화 API는 crypto_alloc_akcipher()로 tfm을 얻고, akcipher_request에 입출력(I/O) scatterlist를 연결한 뒤 crypto_akcipher_encrypt() 또는 crypto_akcipher_decrypt()를 호출하는 형태입니다. 공개키/개인키는 BER/DER로 인코딩된 형태가 필요하다는 점이 대칭 API와 가장 크게 다릅니다.

#include <crypto/akcipher.h>
#include <linux/scatterlist.h>

static int rsa_encrypt_keyblob(const void *pub_der, unsigned int pub_der_len,
                               const u8 *plain, unsigned int plain_len,
                               u8 *cipher, unsigned int *cipher_len)
{
    struct crypto_akcipher *tfm;
    struct akcipher_request *req;
    struct scatterlist src, dst;
    int ret;

    tfm = crypto_alloc_akcipher("rsa", 0, 0);
    if (IS_ERR(tfm))
        return PTR_ERR(tfm);

    ret = crypto_akcipher_set_pub_key(tfm, pub_der, pub_der_len);
    if (ret)
        goto out_free_tfm;

    req = akcipher_request_alloc(tfm, GFP_KERNEL);
    if (!req) {
        ret = -ENOMEM;
        goto out_free_tfm;
    }

    sg_init_one(&src, plain, plain_len);
    sg_init_one(&dst, cipher, *cipher_len);
    akcipher_request_set_crypt(req, &src, &dst, plain_len, *cipher_len);

    ret = crypto_akcipher_encrypt(req);
    if (!ret)
        *cipher_len = req->dst_len;

    akcipher_request_free(req);
out_free_tfm:
    crypto_free_akcipher(tfm);
    return ret;
}

전자서명 API 예제

서명 API는 request 객체를 쓰지 않고 tfm에 직접 crypto_sig_sign() 또는 crypto_sig_verify()를 호출합니다. 상위 계층이 이미 해시를 계산해 둔 상태에서 digest에 대해 서명/검증을 수행하는 식으로 사용하는 경우가 많습니다.

#include <crypto/sig.h>

static int verify_firmware_digest(const void *pub_der, unsigned int pub_der_len,
                                  const u8 *sig, unsigned int sig_len,
                                  const u8 *digest, unsigned int digest_len)
{
    struct crypto_sig *tfm;
    int ret;

    tfm = crypto_alloc_sig("ecdsa", 0, 0);
    if (IS_ERR(tfm))
        return PTR_ERR(tfm);

    ret = crypto_sig_set_pubkey(tfm, pub_der, pub_der_len);
    if (ret)
        goto out_free_tfm;

    ret = crypto_sig_verify(tfm, sig, sig_len, digest, digest_len);

out_free_tfm:
    crypto_free_sig(tfm);
    return ret;
}

서명 출력 버퍼는 crypto_sig_maxsize()로 산정하고, 검증에 넘기는 digest 길이는 상위 프로토콜이 정한 해시 길이와 정확히 맞춰야 합니다. 특히 ECDSA는 곡선 종류와 DER 인코딩 길이에 따라 서명 길이가 가변적일 수 있으므로, 고정 길이 배열을 가정하면 구현이 깨질 수 있습니다.

KPP ECDH 예제

crypto_kpp는 암호문을 만드는 API가 아니라 공유 비밀을 계산하는 API입니다. ECDH에서는 개인키를 struct ecdh로 표현한 뒤 crypto_ecdh_encode_key()로 패킷(Packet) 형태로 포장해 crypto_kpp_set_secret()에 넘깁니다.

#include <crypto/kpp.h>
#include <crypto/ecdh.h>
#include <linux/scatterlist.h>
#include <linux/slab.h>

static int ecdh_shared_secret(const u8 *priv, unsigned int priv_len,
                               const u8 *peer_pub, unsigned int peer_pub_len,
                               u8 *secret, unsigned int *secret_len)
{
    struct crypto_kpp *tfm;
    struct kpp_request *req;
    struct ecdh params = {
        .key = (char *)priv,
        .key_size = priv_len,
    };
    struct scatterlist src, dst;
    char *packed = NULL;
    unsigned int packed_len;
    int ret;

    tfm = crypto_alloc_kpp("ecdh", 0, 0);
    if (IS_ERR(tfm))
        return PTR_ERR(tfm);

    packed_len = crypto_ecdh_key_len(&params);
    packed = kmalloc(packed_len, GFP_KERNEL);
    if (!packed) {
        ret = -ENOMEM;
        goto out_free_tfm;
    }

    ret = crypto_ecdh_encode_key(packed, packed_len, &params);
    if (ret)
        goto out_free_key;

    ret = crypto_kpp_set_secret(tfm, packed, packed_len);
    if (ret)
        goto out_free_key;

    req = kpp_request_alloc(tfm, GFP_KERNEL);
    if (!req) {
        ret = -ENOMEM;
        goto out_free_key;
    }

    sg_init_one(&src, peer_pub, peer_pub_len);
    sg_init_one(&dst, secret, *secret_len);
    kpp_request_set_input(req, &src, peer_pub_len);
    kpp_request_set_output(req, &dst, *secret_len);

    ret = crypto_kpp_compute_shared_secret(req);
    if (!ret)
        *secret_len = req->dst_len;

    kpp_request_free(req);
out_free_key:
    kfree(packed);
out_free_tfm:
    crypto_free_kpp(tfm);
    return ret;
}

커널에서 지원하는 비대칭 알고리즘 전체 목록

TLS 핸드셰이크에서 비대칭 연산의 역할

비대칭 암호의 핵심 사용처는 대칭 세션 키를 안전하게 합의하는 것입니다. TLS 1.3 핸드셰이크를 예로 들면, ECDH(키 합의) → ECDSA(서명 검증) → HKDF(키 파생) → AES-GCM(대칭 암호화) 순서로 비대칭·대칭 연산이 결합됩니다:

커널 모듈 서명 검증 파이프라인

커널 모듈 서명(CONFIG_MODULE_SIG)은 비대칭 암호의 대표적 커널 내 사용처입니다. 빌드 시 개인키로 모듈을 서명하고, 로드 시 내장 공개키로 검증합니다:

키 형식과 DER 인코딩

커널 Crypto API의 비대칭 연산은 키를 DER(Distinguished Encoding Rules) 형식으로 요구합니다. PEM(Base64) 형식이 아닌 바이너리 ASN.1/DER 형태이며, 알고리즘에 따라 구조가 다릅니다:

# ━━━ 키 형식 변환과 커널 호환성 ━━━

# RSA 공개키: PEM → DER 변환
openssl rsa -in rsa_priv.pem -pubout -outform DER -out rsa_pub.der
# → SubjectPublicKeyInfo(SPKI) 형태, crypto_akcipher_set_pub_key()에 직접 전달

# RSA 개인키: PEM → DER 변환 (PKCS#8)
openssl pkcs8 -in rsa_priv.pem -topk8 -nocrypt -outform DER -out rsa_priv.der
# → PKCS#8 형태, crypto_akcipher_set_priv_key()에 전달

# ECDSA P-256 키쌍 생성
openssl ecparam -name prime256v1 -genkey -noout -outform DER -out ec_priv.der
openssl ec -in ec_priv.der -inform DER -pubout -outform DER -out ec_pub.der
# → crypto_sig_set_pubkey()에 DER 형태 직접 전달

# 커널 모듈 서명용 키 생성 (커널 빌드 자동)
# certs/signing_key.pem — 빌드 시 자동 생성
# → .builtin_trusted_keys 키링에 X.509 인증서로 내장

# DER 키 구조 확인
openssl asn1parse -in rsa_pub.der -inform DER
#   0:d=0 hl=4 l=290 cons: SEQUENCE
#   4:d=1 hl=2 l=  13 cons:  SEQUENCE        ← AlgorithmIdentifier
#  19:d=1 hl=4 l=271 prim:  BIT STRING       ← 공개키 데이터

비대칭 연산 HW 가속

비대칭 연산은 대칭 연산에 비해 수백~수천 배 느리기 때문에, TLS 핸드셰이크가 많은 환경에서 HW 가속의 효과가 큽니다. 커널의 주요 HW 가속기별 지원 현황입니다:

비대칭 연산 성능 특성

해시 사용 예제

해시(Hash)는 임의 길이 데이터를 고정 길이 다이제스트(Digest)로 축약하는 일방향 함수입니다. Crypto API는 shash(동기 해시)와 ahash(비동기 해시) 두 인터페이스를 제공합니다. 대부분의 경우 shash가 간결하고 충분하며, HW DMA 해시 엔진을 사용할 때만 ahash가 필요합니다:

#include <crypto/hash.h>
#include <linux/slab.h>

static int calc_sha256(const u8 *data, unsigned int len, u8 *digest)
{
    struct crypto_shash *tfm;
    struct shash_desc *desc;
    int ret;

    tfm = crypto_alloc_shash("sha256", 0, 0);
    if (IS_ERR(tfm))
        return PTR_ERR(tfm);

    desc = kmalloc(sizeof(*desc) + crypto_shash_descsize(tfm), GFP_KERNEL);
    if (!desc) {
        crypto_free_shash(tfm);
        return -ENOMEM;
    }

    desc->tfm = tfm;
    ret = crypto_shash_digest(desc, data, len, digest);
    kfree(desc);
    crypto_free_shash(tfm);
    return ret;
}

/* 스택 할당 대안: SHASH_DESC_ON_STACK 매크로 사용
 * 힙 할당 오버헤드 없이 스택에 shash_desc를 직접 배치합니다.
 * 단, descsize가 크면 스택 사용량 초과 위험이 있으므로
 * CONFIG_FRAME_WARN을 초과하지 않는 작은 알고리즘에 적합합니다. */
static int calc_sha256_stack(const u8 *data, unsigned int len, u8 *digest)
{
    struct crypto_shash *tfm = crypto_alloc_shash("sha256", 0, 0);
    SHASH_DESC_ON_STACK(desc, tfm);  /* 스택에 shash_desc 할당 */
    int ret;

    if (IS_ERR(tfm))
        return PTR_ERR(tfm);
    desc->tfm = tfm;
    ret = crypto_shash_digest(desc, data, len, digest);
    shash_desc_zero(desc);          /* 민감 데이터 스택 소거 */
    crypto_free_shash(tfm);
    return ret;
}

HMAC 사용 예제

HMAC(Hash-based Message Authentication Code)은 해시 함수에 비밀 키를 결합하여 메시지 인증 코드를 생성합니다. Crypto API에서 HMAC은 "hmac(sha256)"처럼 해시 알고리즘을 감싸는 템플릿으로 사용하며, shash 인터페이스를 그대로 사용합니다. 차이점은 crypto_shash_setkey()로 MAC 키를 설정해야 한다는 것뿐입니다:

#include <crypto/hash.h>

/* ━━━ HMAC-SHA256 메시지 인증 코드 생성 ━━━ */
static int calc_hmac_sha256(const u8 *key, unsigned int key_len,
                            const u8 *data, unsigned int data_len,
                            u8 *mac)
{
    struct crypto_shash *tfm;
    struct shash_desc *desc;
    int ret;

    /* hmac(sha256) 템플릿으로 tfm 할당 */
    tfm = crypto_alloc_shash("hmac(sha256)", 0, 0);
    if (IS_ERR(tfm))
        return PTR_ERR(tfm);

    /* HMAC 키 설정 — shash와 달리 setkey가 필수 */
    ret = crypto_shash_setkey(tfm, key, key_len);
    if (ret)
        goto out_free;

    desc = kmalloc(sizeof(*desc) + crypto_shash_descsize(tfm), GFP_KERNEL);
    if (!desc) { ret = -ENOMEM; goto out_free; }

    desc->tfm = tfm;
    ret = crypto_shash_digest(desc, data, data_len, mac);
    /* mac에 32바이트 HMAC-SHA256 결과 기록 */

    kfree(desc);
out_free:
    crypto_free_shash(tfm);
    return ret;
}

증분 해시 (init/update/final)

데이터가 여러 조각으로 나뉘어 있거나 스트리밍으로 도착하는 경우, digest() 한 번 호출 대신 init → update(반복) → final 3단계를 사용합니다. 이 패턴은 IMA 무결성 검증, 파일 해시, 네트워크 패킷 누적 해시 등에서 사용됩니다:

#include <crypto/hash.h>

/* ━━━ 증분 해시: 여러 조각 데이터를 순차적으로 해시 ━━━ */
static int hash_file_chunks(struct crypto_shash *tfm,
                            const u8 **chunks, const unsigned int *lens,
                            int nchunks, u8 *digest)
{
    SHASH_DESC_ON_STACK(desc, tfm);
    int i, ret;

    desc->tfm = tfm;

    /* 1단계: 초기화 — 내부 해시 상태를 IV로 설정 */
    ret = crypto_shash_init(desc);
    if (ret)
        goto out;

    /* 2단계: 데이터 조각별로 update — 중간 상태 누적 */
    for (i = 0; i < nchunks; i++) {
        ret = crypto_shash_update(desc, chunks[i], lens[i]);
        if (ret)
            goto out;
    }

    /* 3단계: 최종화 — 패딩 + 마지막 블록 처리 → 다이제스트 출력 */
    ret = crypto_shash_final(desc, digest);

out:
    shash_desc_zero(desc);
    return ret;
}

/* 사용 예: 커널 모듈에서 분산된 데이터 해시 */
static int verify_integrity(void)
{
    struct crypto_shash *tfm;
    u8 digest[32];
    const u8 *chunks[] = { header, body, trailer };
    const unsigned int lens[] = { hdr_len, body_len, trl_len };

    tfm = crypto_alloc_shash("sha256", 0, 0);
    if (IS_ERR(tfm))
        return PTR_ERR(tfm);

    hash_file_chunks(tfm, chunks, lens, 3, digest);
    /* digest를 예상 값과 비교 */

    crypto_free_shash(tfm);
    return 0;
}

대칭 암호 예제

대칭 암호(skcipher)는 동일한 키로 암호화와 복호화를 수행합니다. crypto_skcipher API는 블록 암호 모드(CBC, CTR, XTS 등)와 스트림 암호(ChaCha20)를 통합 인터페이스로 제공합니다. 4단계 라이프사이클을 따릅니다:

#include <crypto/skcipher.h>
#include <linux/scatterlist.h>

/* ━━━ AES-CBC 대칭 암호화 전체 예제 (비동기 지원) ━━━ */
static int aes_cbc_encrypt(const u8 *key, unsigned int key_len,
                           u8 *iv, u8 *data, unsigned int data_len)
{
    struct crypto_skcipher *tfm;
    struct skcipher_request *req;
    struct scatterlist sg;
    u8 iv_local[16];
    int ret;
    DECLARE_CRYPTO_WAIT(wait);

    /* ① tfm 할당 — 커널이 최적 구현을 자동 선택 */
    tfm = crypto_alloc_skcipher("cbc(aes)", 0, 0);
    if (IS_ERR(tfm))
        return PTR_ERR(tfm);

    ret = crypto_skcipher_setkey(tfm, key, key_len);
    if (ret)
        goto out_free_tfm;

    /* ② req 할당 + 콜백 설정 */
    req = skcipher_request_alloc(tfm, GFP_KERNEL);
    if (!req) { ret = -ENOMEM; goto out_free_tfm; }

    skcipher_request_set_callback(req,
        CRYPTO_TFM_REQ_MAY_BACKLOG | CRYPTO_TFM_REQ_MAY_SLEEP,
        crypto_req_done, &wait);

    /* ③ scatterlist + IV 설정 (in-place 암호화) */
    sg_init_one(&sg, data, data_len);
    memcpy(iv_local, iv, 16);  /* IV 복사본 — 일부 드라이버가 원본 수정 */
    skcipher_request_set_crypt(req, &sg, &sg, data_len, iv_local);

    /* ④ 암호화 수행 — 동기·비동기 투명 처리 */
    ret = crypto_wait_req(crypto_skcipher_encrypt(req), &wait);

    memzero_explicit(iv_local, sizeof(iv_local));
    skcipher_request_free(req);
out_free_tfm:
    crypto_free_skcipher(tfm);
    return ret;  /* 0: 성공, 음수: 에러 */
}

AES-XTS 디스크 암호화 예제

XTS(XEX-based Tweaked codebook mode with ciphertext Stealing)는 디스크 암호화(dm-crypt, fscrypt)의 표준 모드입니다. CBC와 달리 패딩이 불필요하고, 섹터 번호를 tweak으로 사용하여 동일 평문이라도 섹터마다 다른 암호문을 생성합니다. XTS는 키 크기가 일반 AES의 2배입니다(AES-256-XTS는 64바이트 키 사용):

#include <crypto/skcipher.h>
#include <linux/scatterlist.h>

/* ━━━ AES-XTS 섹터 암호화 (dm-crypt 패턴) ━━━ */
static int xts_encrypt_sector(struct crypto_skcipher *tfm,
                               u8 *sector_data, unsigned int sector_size,
                               u64 sector_num)
{
    struct skcipher_request *req;
    struct scatterlist sg;
    u8 iv[16];
    int ret;
    DECLARE_CRYPTO_WAIT(wait);

    req = skcipher_request_alloc(tfm, GFP_NOIO);
    if (!req)
        return -ENOMEM;

    skcipher_request_set_callback(req,
        CRYPTO_TFM_REQ_MAY_BACKLOG | CRYPTO_TFM_REQ_MAY_SLEEP,
        crypto_req_done, &wait);

    /* XTS IV: 섹터 번호를 리틀 엔디안으로 배치 */
    memset(iv, 0, sizeof(iv));
    *(__le64 *)iv = cpu_to_le64(sector_num);

    sg_init_one(&sg, sector_data, sector_size);
    skcipher_request_set_crypt(req, &sg, &sg, sector_size, iv);

    ret = crypto_wait_req(crypto_skcipher_encrypt(req), &wait);

    skcipher_request_free(req);
    return ret;
}

/* 초기화 예 (dm-crypt 스타일) */
static struct crypto_skcipher *setup_xts(const u8 *master_key)
{
    struct crypto_skcipher *tfm;

    /* xts(aes): AES-256-XTS는 64바이트 키 (암호화 키 32B + tweak 키 32B) */
    tfm = crypto_alloc_skcipher("xts(aes)", 0, 0);
    if (IS_ERR(tfm))
        return tfm;

    if (crypto_skcipher_setkey(tfm, master_key, 64)) {
        crypto_free_skcipher(tfm);
        return ERR_PTR(-EINVAL);
    }
    return tfm;
}

Scatterlist 심화 — 물리 메모리 분산 I/O

Crypto API의 모든 데이터 전달은 scatterlist(SG)를 통해 이루어집니다. scatterlist는 물리적으로 분산된 메모리 페이지들을 연결 목록으로 표현하는 구조체로, DMA 친화적인 zero-copy 처리를 가능하게 합니다. 네트워크 패킷의 SKB 프래그먼트, 블록 I/O의 바이오벡(bvec), 파일시스템의 페이지 캐시 등 커널의 데이터는 대부분 비연속적이므로, SG 없이는 매번 memcpy로 연속 버퍼를 만들어야 합니다:

#include <linux/scatterlist.h>

/* ━━━ Scatterlist 구성 패턴 ━━━ */

/* 패턴 1: 단일 연속 버퍼 → SG 1개 */
struct scatterlist sg;
sg_init_one(&sg, buf, buf_len);

/* 패턴 2: 여러 버퍼 → SG 배열 */
struct scatterlist sg[3];
sg_init_table(sg, 3);               /* 배열 초기화 + 마지막 엔트리 표시 */
sg_set_buf(&sg[0], header, hdr_len);
sg_set_buf(&sg[1], body, body_len);
sg_set_buf(&sg[2], trailer, trl_len);

/* 패턴 3: 페이지 기반 (네트워크/블록 I/O) */
sg_set_page(&sg[0], page, PAGE_SIZE, offset);

/* 패턴 4: in-place 암호화 (src == dst) */
skcipher_request_set_crypt(req, &sg, &sg, len, iv);
/* → src와 dst가 같으면 원본 버퍼를 직접 암호문으로 덮어씀 */

/* 패턴 5: 별도 출력 버퍼 (src ≠ dst) */
struct scatterlist src_sg, dst_sg;
sg_init_one(&src_sg, plaintext, len);
sg_init_one(&dst_sg, ciphertext, len);
skcipher_request_set_crypt(req, &src_sg, &dst_sg, len, iv);

하드웨어 가속

Crypto API의 priority 기반 자동 선택 메커니즘을 통해, 사용자 코드 변경 없이 하드웨어 가속이 투명하게 적용됩니다. 동일 알고리즘의 여러 구현이 등록되면 priority가 가장 높은 것이 자동 선택됩니다:

# ━━━ 하드웨어 가속 상태 확인 ━━━

# 등록된 모든 알고리즘과 드라이버·우선순위 확인
grep -E "^name|^driver|^priority|^type" /proc/crypto | head -20
# name         : cbc(aes)
# driver       : cbc-aes-aesni      ← AES-NI 가속
# priority     : 400
# type         : skcipher

# CPU 암호 명령어 지원 확인
grep -oE "aes|sha_ni|pclmulqdq|crc32c" /proc/cpuinfo | sort -u
# aes pclmulqdq sha_ni crc32c

# ARM CE 확인
grep -oE "aes|sha2|pmull|crc32" /proc/cpuinfo | sort -u

# HW 가속기 모듈 로드 확인
lsmod | grep -E "aesni|caam|qat|otx2_cpt|hisi_sec"

비동기 암호화 (Async Crypto)

커널 Crypto API의 비동기(Asynchronous) 처리 모델은 HW 가속기와 CPU를 병렬로 동작시키는 핵심 메커니즘입니다. 동기(synchronous) 알고리즘(AES-NI 등)은 함수가 반환되면 이미 완료되지만, 비동기 알고리즘(QAT, CAAM, CPT 등)은 요청을 큐에 제출한 뒤 즉시 반환하고, HW가 완료되면 콜백(callback)으로 결과를 통지합니다. 이 차이를 이해하지 않으면 데이터 손상, deadlock, use-after-free 등 치명적 버그가 발생합니다.

동기 vs 비동기 처리 모델

Crypto API의 모든 알고리즘은 /proc/crypto의 async 필드로 동기/비동기 여부를 확인할 수 있습니다. 동일한 알고리즘 이름(cbc(aes) 등)에 대해 동기·비동기 구현이 공존하며, priority가 높은 구현이 자동 선택됩니다:

# /proc/crypto에서 동기·비동기 구분 확인
grep -A4 "^name.*cbc(aes)" /proc/crypto
# name         : cbc(aes)
# driver       : cbc-aes-aesni        ← AES-NI (동기)
# priority     : 400
# async        : no                   ← 동기: 즉시 완료
# ---
# name         : cbc(aes)
# driver       : cbc-aes-caam         ← CAAM (비동기)
# priority     : 3000
# async        : yes                  ← 비동기: 콜백으로 완료

# CAAM priority(3000) > AES-NI priority(400)
# → i.MX/Layerscape에서 crypto_alloc_skcipher("cbc(aes)")는 CAAM을 자동 선택

반환값 계약과 완료 통지

Crypto API 비동기 모델에서 가장 중요한 것은 반환값과 콜백의 관계입니다. crypto_skcipher_encrypt(), crypto_aead_encrypt(), crypto_ahash_digest() 등 모든 비동기 API 함수는 동일한 반환값 규약을 따릅니다:

콜백 메커니즘 상세

비동기 콜백은 skcipher_request_set_callback() / aead_request_set_callback() / ahash_request_set_callback()으로 등록합니다. 콜백 함수의 시그니처와 호출 컨텍스트를 이해하는 것이 안전한 비동기 코드 작성의 핵심입니다:

/* ━━━ 비동기 콜백 함수 작성 패턴 ━━━ */

/* 콜백 함수 시그니처 — 모든 비동기 API 공통 */
static void my_crypto_done(void *data, int err)
{
    struct my_async_result *result = data;

    /* 백로그 경로: 1차 콜백은 "큐 진입 알림"일 뿐 */
    if (err == -EINPROGRESS)
        return;  /* 아직 완료 아님, 2차 콜백을 기다림 */

    /* 여기가 진짜 완료 지점 — err=0이면 성공, 음수면 에러 */
    result->err = err;
    complete(&result->completion);
}

/* 콜백 결과를 전달받을 구조체 */
struct my_async_result {
    struct completion completion;
    int err;
};

crypto_wait_req() — 비동기를 동기처럼 사용하기

process context(sleep 가능)에서는 콜백 기반 상태 머신을 직접 구현할 필요 없이 DECLARE_CRYPTO_WAIT와 crypto_wait_req()를 사용하면 동기·비동기 양쪽을 동일한 코드로 처리할 수 있습니다. 이 패턴은 dm-crypt, fscrypt, IKE 등 커널 내 대부분의 Crypto API 소비자가 사용합니다:

/* ━━━ crypto_wait_req() 사용 예 — 가장 간결한 비동기 패턴 ━━━ */

#include <crypto/skcipher.h>

static int encrypt_data(struct crypto_skcipher *tfm,
                       u8 *data, unsigned int len, u8 *iv)
{
    struct skcipher_request *req;
    struct scatterlist sg;
    DECLARE_CRYPTO_WAIT(wait);  /* completion + err 포함 */
    int ret;

    req = skcipher_request_alloc(tfm, GFP_KERNEL);
    if (!req)
        return -ENOMEM;

    sg_init_one(&sg, data, len);
    skcipher_request_set_crypt(req, &sg, &sg, len, iv);
    skcipher_request_set_callback(req,
        CRYPTO_TFM_REQ_MAY_BACKLOG | CRYPTO_TFM_REQ_MAY_SLEEP,
        crypto_req_done, &wait);     /* 커널 내장 콜백 */

    /* 한 줄로 동기·비동기 모두 처리 */
    ret = crypto_wait_req(crypto_skcipher_encrypt(req), &wait);
    /* ret == 0: 성공 (동기든 비동기든 무관) */
    /* ret < 0: 에러 (암호화 실패) */

    skcipher_request_free(req);
    return ret;
}

비동기 요청 라이프사이클

비동기 암호 요청은 4단계 라이프사이클을 거칩니다. 각 단계에서 메모리 소유권이 이동하므로 순서를 지키는 것이 중요합니다:

완료 통지 모델 3종 비교

HW 가속기가 암호 연산을 완료한 뒤 결과를 CPU에 통지하는 방식은 3가지입니다. 워크로드 특성에 따라 최적 모델이 달라집니다:

백로그(Backlog) 메커니즘

HW 가속기의 하드웨어 큐는 유한합니다. 큐가 가득 찬 상태에서 새 요청이 들어오면, CRYPTO_TFM_REQ_MAY_BACKLOG 플래그가 설정된 경우 커널은 요청을 소프트웨어 백로그 리스트에 추가하고 -EBUSY를 반환합니다. HW 큐에 빈 슬롯이 생기면 백로그에서 요청을 꺼내 자동으로 재제출합니다:

/* ━━━ 백로그 처리가 포함된 완전한 비동기 패턴 ━━━ */

/* 콜백 — 백로그를 올바르게 처리 */
static void my_crypto_complete(void *data, int err)
{
    struct my_ctx *ctx = data;

    if (err == -EINPROGRESS) {
        /* 백로그 경로 1차 콜백: 큐에 진입한 알림
         * → 아직 처리 완료가 아니므로 데이터에 접근하면 안 됨
         * → 필요하면 통계 카운터만 업데이트 */
        atomic_dec(&ctx->backlog_count);
        return;
    }

    /* 진짜 완료 — err=0이면 성공 */
    ctx->err = err;
    complete(&ctx->done);
}

/* 제출 측 */
int ret = crypto_skcipher_encrypt(req);

switch (ret) {
case 0:
    /* 즉시 완료 — 결과 사용 가능 */
    process_result(req);
    break;
case -EINPROGRESS:
    /* HW에서 처리 중 — 콜백으로 완료 통지 */
    break;
case -EBUSY:
    /* 큐 포화 → 백로그 진입 — 결국 콜백으로 완료 */
    atomic_inc(&ctx->backlog_count);
    break;
default:
    /* 에러 (콜백 없음) — 직접 에러 처리 */
    handle_error(ret);
    break;
}

crypto_engine — HW 드라이버의 비동기 큐 관리

crypto_engine은 커널이 HW 가속기 드라이버를 위해 제공하는 비동기 큐 관리 프레임워크입니다. 드라이버가 직접 큐잉·백로그·완료 통지를 구현하는 대신, crypto_engine에 위임하면 Crypto API 규약에 맞는 비동기 처리가 자동으로 이루어집니다:

AEAD (Authenticated Encryption with Associated Data)

AEAD(Authenticated Encryption with Associated Data)는 암호화(기밀성)와 인증(무결성·진본성)을 단일 원자적 연산으로 결합하는 암호 프리미티브입니다. 전통적인 "encrypt-then-MAC" 조합과 달리 키 관리가 단순하고, 암호화·인증 순서 실수로 인한 취약점(Padding Oracle 등)이 구조적으로 불가능합니다. 커널에서 IPsec ESP, kTLS, WireGuard, dm-integrity+dm-crypt 등 거의 모든 현대 암호 프로토콜이 AEAD를 사용합니다.

AEAD 동작 원리

AEAD 알고리즘은 4개의 입력을 받아 암호문과 인증 태그(Authentication Tag)를 생성합니다:

커널에서 지원하는 주요 AEAD 알고리즘

scatterlist 메모리 레이아웃

AEAD 요청에서 가장 실수가 많은 부분이 scatterlist 레이아웃입니다. encrypt와 decrypt에서 src/dst의 구성이 비대칭적이며, cryptlen의 의미도 다릅니다:

AEAD API 사용 패턴

/* ━━━ AEAD (AES-GCM) 암호화/복호화 전체 예제 ━━━ */

#include <crypto/aead.h>
#include <linux/scatterlist.h>

#define GCM_IV_SIZE   12   /* AES-GCM 표준 IV */
#define GCM_TAG_SIZE  16   /* 128-bit 인증 태그 */

/* ── 암호화 ── */
static int aead_encrypt_example(const u8 *key, unsigned int key_len,
                               const u8 *iv, const u8 *aad, unsigned int aad_len,
                               const u8 *plaintext, unsigned int pt_len,
                               u8 *output)  /* output 크기 = aad_len + pt_len + GCM_TAG_SIZE */
{
    struct crypto_aead *tfm;
    struct aead_request *req;
    struct scatterlist src_sg[2], dst_sg[3];
    u8 iv_local[GCM_IV_SIZE];
    int ret;
    DECLARE_CRYPTO_WAIT(wait);

    /* 1. tfm 할당 + 키·태그 크기 설정 */
    tfm = crypto_alloc_aead("gcm(aes)", 0, 0);
    if (IS_ERR(tfm))
        return PTR_ERR(tfm);

    ret = crypto_aead_setkey(tfm, key, key_len);
    if (ret) goto out_free_tfm;

    ret = crypto_aead_setauthsize(tfm, GCM_TAG_SIZE);
    if (ret) goto out_free_tfm;

    /* 2. request 할당 + 콜백 설정 */
    req = aead_request_alloc(tfm, GFP_KERNEL);
    if (!req) { ret = -ENOMEM; goto out_free_tfm; }

    aead_request_set_callback(req,
        CRYPTO_TFM_REQ_MAY_BACKLOG | CRYPTO_TFM_REQ_MAY_SLEEP,
        crypto_req_done, &wait);

    /* 3. scatterlist 구성 */
    /* src: [AAD | Plaintext] */
    sg_init_table(src_sg, 2);
    sg_set_buf(&src_sg[0], aad, aad_len);
    sg_set_buf(&src_sg[1], plaintext, pt_len);

    /* dst: [AAD | Ciphertext | Tag] */
    sg_init_table(dst_sg, 3);
    sg_set_buf(&dst_sg[0], output, aad_len);               /* AAD 복사 영역 */
    sg_set_buf(&dst_sg[1], output + aad_len, pt_len);      /* 암호문 */
    sg_set_buf(&dst_sg[2], output + aad_len + pt_len, GCM_TAG_SIZE); /* 태그 */

    /* 4. 요청 파라미터 설정 */
    memcpy(iv_local, iv, GCM_IV_SIZE);
    aead_request_set_crypt(req, src_sg, dst_sg, pt_len, iv_local);
    /*                                         ^^^^^^ Encrypt: 평문 길이 */
    aead_request_set_ad(req, aad_len);

    /* 5. 암호화 수행 (비동기 지원) */
    ret = crypto_wait_req(crypto_aead_encrypt(req), &wait);

    aead_request_free(req);
out_free_tfm:
    crypto_free_aead(tfm);
    return ret;
}

/* ── 복호화 ── */
static int aead_decrypt_example(const u8 *key, unsigned int key_len,
                               const u8 *iv, const u8 *aad, unsigned int aad_len,
                               const u8 *ct_and_tag, unsigned int ct_len,
                               u8 *output)  /* output 크기 = aad_len + ct_len */
{
    /* ... tfm/req 할당 동일 ... */

    /* src: [AAD | Ciphertext | Tag] */
    aead_request_set_crypt(req, src_sg, dst_sg,
        ct_len + GCM_TAG_SIZE, iv_local);
    /* ^^^^^^^^^^^^^^^^^^^^^^^^ Decrypt: 암호문 + 태그 길이! */
    aead_request_set_ad(req, aad_len);

    ret = crypto_wait_req(crypto_aead_decrypt(req), &wait);
    /* ret == -EBADMSG: 인증 태그 불일치 → 데이터 위변조 감지 */
    /* ret == 0: 복호화 성공, output에 평문 기록됨 */
}

프로토콜별 AEAD 적용 구조

커널의 주요 네트워크·스토리지 프로토콜은 각각 다른 방식으로 AEAD를 적용합니다. 아래 다이어그램은 각 프로토콜이 AAD, 평문, 태그를 어떻게 배치하는지 보여줍니다:

AES-GCM 내부 동작

AES-GCM은 커널에서 가장 많이 사용되는 AEAD 알고리즘입니다. 내부적으로 AES-CTR(Counter Mode)로 암호화하고, GHASH(Galois Hash)로 인증 태그를 생성합니다. AES-NI와 PCLMULQDQ(캐리 없는 곱셈) 명령어를 사용하면 두 연산을 파이프라인으로 병렬 처리할 수 있습니다:

authenc(HMAC,CBC) vs 네이티브 AEAD 비교

커널의 authenc 템플릿은 기존 블록 암호(CBC)와 MAC(HMAC)을 조합하여 AEAD 인터페이스를 제공하는 호환 레이어입니다. 네이티브 AEAD(GCM, ChaCha20-Poly1305)와의 핵심 차이를 이해하면 적절한 알고리즘을 선택할 수 있습니다:

커널 난수 생성기

암호화 시스템의 안전성은 키·IV·Nonce의 예측 불가능성에 달려 있으며, 이를 제공하는 것이 난수 생성기(Random Number Generator)입니다. 리눅스 커널은 다계층 난수 아키텍처를 사용합니다: 하드웨어 엔트로피 소스(TRNG/hwrng)가 물리적 무작위성을 수집하고, 커널 엔트로피 풀이 이를 축적한 뒤, ChaCha20 기반 CRNG(Cryptographically Secure PRNG)가 고속으로 난수를 생성합니다. Crypto API의 crypto_rng 인터페이스는 NIST SP 800-90A DRBG를 FIPS 호환 방식으로 제공합니다.

커널 난수 아키텍처

난수 API 비교 — 언제 무엇을 쓸 것인가

커널 공간 난수 API 사용 예제

#include <linux/random.h>

/* ━━━ 범용 암호학적 난수 (가장 일반적) ━━━ */

u8 aes_key[32];
get_random_bytes(aes_key, sizeof(aes_key));  /* 256-bit AES 키 */

u8 iv[16];
get_random_bytes(iv, sizeof(iv));             /* CBC IV */

u8 nonce[12];
get_random_bytes(nonce, sizeof(nonce));       /* GCM Nonce */

/* ━━━ 정수 난수 ━━━ */

u32 hash_seed = get_random_u32();             /* 해시 테이블 시드 */
u64 cookie = get_random_u64();                /* TCP SYN 쿠키 */
u32 idx = get_random_u32_below(100);          /* 0~99 범위 */

/* ━━━ 초기 부팅 시 주의사항 ━━━ */
/* 부팅 초기에는 엔트로피 풀이 충분히 채워지지 않을 수 있음.
 * get_random_bytes()는 CRNG가 초기화된 후에만 완전한 품질을 보장.
 * wait_for_random_bytes()로 초기화 완료를 기다릴 수 있음 */
ret = wait_for_random_bytes();  /* CRNG 준비될 때까지 대기 */
if (ret)
    pr_warn("CRNG not ready, random may be weak\n");

Crypto API DRBG — FIPS 호환 난수 생성

Crypto API의 crypto_rng 인터페이스는 NIST SP 800-90A 규격의 DRBG(Deterministic Random Bit Generator)를 제공합니다. 일반 용도에서는 get_random_bytes()가 충분하지만, FIPS 인증 환경이나 테스트 벡터 재현이 필요한 경우 DRBG를 직접 사용합니다:

#include <crypto/rng.h>

/* ━━━ Crypto API DRBG 사용 예제 ━━━ */
static int generate_fips_random(u8 *out, unsigned int len)
{
    struct crypto_rng *drbg;
    u8 seed[64];
    int ret;

    /* 1. DRBG 인스턴스 할당 */
    drbg = crypto_alloc_rng("drbg_nopr_hmac_sha256", 0, 0);
    if (IS_ERR(drbg))
        return PTR_ERR(drbg);

    /* 2. 엔트로피 시드 준비 → DRBG에 주입 */
    get_random_bytes(seed, crypto_rng_seedsize(drbg));
    ret = crypto_rng_reset(drbg, seed, crypto_rng_seedsize(drbg));
    if (ret)
        goto out;

    /* 3. DRBG에서 난수 생성 */
    ret = crypto_rng_get_bytes(drbg, out, len);
    /* ret == 0: 성공, -EINVAL: 파라미터 오류 */

out:
    memzero_explicit(seed, sizeof(seed));
    crypto_free_rng(drbg);
    return ret;
}

엔트로피 소스와 HW RNG

커널이 수집하는 엔트로피 소스와 각각의 특성입니다. 다중 소스를 혼합(mixing)하여 단일 소스의 결함이 전체 시스템을 위협하지 않도록 합니다:

ChaCha20 CRNG 내부 구조

리눅스 6.x의 핵심 CRNG는 ChaCha20 스트림 암호 기반입니다. CPU별(per-CPU) 독립 상태를 유지하여 lock-free 고속 생성이 가능합니다:

/* drivers/char/random.c — ChaCha20 CRNG 핵심 구조 (간소화) */

struct crng_state {
    u32 state[16];     /* ChaCha20 상태 (512비트) */
    unsigned long birth; /* 마지막 reseed 시각 */
};

/* per-CPU CRNG — 각 CPU가 독립 상태를 보유 */
static DEFINE_PER_CPU(struct crng_state, crngs);

/* get_random_bytes() 내부 동작 (간소화) */
void get_random_bytes(void *buf, size_t len)
{
    struct crng_state *crng = this_cpu_ptr(&crngs);

    /* 1. reseed 필요 여부 확인 (5분 또는 256B 출력마다) */
    if (crng_needs_reseed(crng))
        crng_reseed(crng);  /* 엔트로피 풀에서 256비트 시드 추출 → 키 갱신 */

    /* 2. ChaCha20 블록 생성 → buf에 복사 */
    chacha20_block(crng->state, buf);

    /* 3. backtrack 방지: 키 부분을 출력에서 즉시 갱신 */
    crng_fast_key_erasure(crng->state);
    /* → 과거 출력에서 키를 역추적하는 것이 불가능 */
}

커널 설정 옵션 (Kconfig)

Crypto Framework 기능은 CONFIG_CRYPTO_* 옵션으로 세밀하게 제어됩니다. 필요한 알고리즘과 드라이버만 선택하면 커널 크기를 줄이고 공격 표면을 최소화할 수 있습니다:

# ━━━ 커널 설정 확인 및 조정 ━━━

# 현재 커널의 Crypto 설정 확인
zcat /proc/config.gz | grep CONFIG_CRYPTO | head -30

# 또는 .config에서 확인
grep CONFIG_CRYPTO .config | grep -v '^#'

# 최소 필수 설정 (서버 용도)
# CONFIG_CRYPTO=y
# CONFIG_CRYPTO_AES=y (fallback)
# CONFIG_CRYPTO_AES_NI_INTEL=y (x86)
# CONFIG_CRYPTO_SHA256=y
# CONFIG_CRYPTO_GCM=y
# CONFIG_CRYPTO_HMAC=y
# CONFIG_CRYPTO_MANAGER=y

tcrypt 벤치마크와 자가 테스트

커널은 Crypto API 알고리즘의 정확성과 성능을 검증하기 위한 두 가지 내장 도구를 제공합니다:

자가 테스트 (testmgr)

알고리즘이 crypto_register_alg()으로 등록될 때, testmgr.c의 자가 테스트가 자동으로 실행됩니다. NIST 테스트 벡터 등 미리 정의된 입력/출력 쌍으로 구현의 정확성을 검증합니다:

# 자가 테스트 결과 확인 — /proc/crypto의 selftest 필드
grep -B2 -A1 "selftest" /proc/crypto | head -20
# name         : cbc(aes)
# driver       : cbc-aes-aesni
# selftest     : passed         ← 정상
# ---
# selftest     : unknown        ← 테스트 벡터 없음 (경고)

# FIPS 모드에서 자가 테스트 실패 시
# → 알고리즘 등록 자체가 거부됨 → 패닉 가능
# dmesg에 "alg: ... Test ... failed" 메시지 출력

tcrypt 벤치마크 모듈

tcrypt는 Crypto API 알고리즘의 처리량(throughput)과 지연(latency)을 측정하는 커널 모듈입니다. modprobe로 로드하면서 mode 파라미터로 벤치마크 유형을 지정합니다:

# ━━━ tcrypt 벤치마크 사용법 ━━━

# AES-CBC 속도 테스트 (mode=200: skcipher 속도 테스트)
modprobe tcrypt mode=200 sec=1
# → dmesg에 블록 크기별 처리량 출력
dmesg | tail -50
# test 1 (128 bit key, 16 byte blocks):    ... MB/s
# test 1 (128 bit key, 1024 byte blocks):  ... MB/s
# test 1 (128 bit key, 8192 byte blocks):  ... MB/s

# SHA-256 해시 속도 테스트 (mode=300: hash 속도 테스트)
modprobe tcrypt mode=300 sec=1

# AES-GCM 속도 테스트 (mode=211)
modprobe tcrypt mode=211 sec=1

# 주요 mode 번호
# 200: AES-CBC    211: AES-GCM    215: ChaCha20-Poly1305
# 300: SHA-256    312: HMAC-SHA256
# 400: RSA        401: ECDH       402: ECDSA

# 모든 알고리즘 속도 테스트 (시간 소요 큼)
modprobe tcrypt mode=0 sec=1

# 테스트 완료 후 모듈 제거
rmmod tcrypt

주요 알고리즘 카탈로그

사용자 공간(User Space) 인터페이스 (AF_ALG)

/* 사용자 공간에서 커널 Crypto Framework (Crypto API) 사용 */
int sockfd = socket(AF_ALG, SOCK_SEQPACKET, 0);

struct sockaddr_alg sa = {
    .salg_family = AF_ALG,
    .salg_type   = "hash",
    .salg_name   = "sha256",
};
bind(sockfd, (struct sockaddr *)&sa, sizeof(sa));

int opfd = accept(sockfd, NULL, NULL);
write(opfd, data, data_len);
read(opfd, digest, 32);  /* SHA-256 결과 */

AF_ALG 사용자 공간 인터페이스

AF_ALG은 사용자 공간에서 커널 Crypto API를 직접 사용할 수 있는 소켓(Socket) 인터페이스입니다. 별도의 암호 라이브러리 없이 커널에 등록된 모든 암호화 가속기(AES-NI, QAT 등)를 활용할 수 있으며, splice()를 통한 zero-copy 전송도 지원합니다.

AF_ALG 아키텍처

AF_ALG 소켓은 4단계 라이프사이클을 따릅니다:

/* AF_ALG 기본 패턴 */
int sockfd, connfd;
struct sockaddr_alg sa = {
    .salg_family = AF_ALG,
    .salg_type   = "skcipher",  /* "hash", "aead", "rng" */
    .salg_name   = "cbc(aes)",  /* 알고리즘 이름 */
};

/* 1. 소켓 생성 + 알고리즘 바인드 */
sockfd = socket(AF_ALG, SOCK_SEQPACKET, 0);
bind(sockfd, (struct sockaddr *)&sa, sizeof(sa));

/* 2. 키 설정 (skcipher/aead만) */
setsockopt(sockfd, SOL_ALG, ALG_SET_KEY, key, key_len);

/* 3. 연결 소켓 생성 (세션) */
connfd = accept(sockfd, NULL, 0);

/* 4. 데이터 송수신 (IV/AAD는 cmsg로 전달) */
sendmsg(connfd, &msg, 0);   /* 평문 + cmsg(IV, op) */
read(connfd, out, out_len); /* 암호문 수신 */

close(connfd);
close(sockfd);

해시 예제 (SHA-256)

#include <linux/if_alg.h>
#include <sys/socket.h>

int sha256_af_alg(const void *data, size_t len,
                  unsigned char digest[32])
{
    struct sockaddr_alg sa = {
        .salg_family = AF_ALG,
        .salg_type   = "hash",
        .salg_name   = "sha256",
    };
    int sockfd, connfd;

    sockfd = socket(AF_ALG, SOCK_SEQPACKET, 0);
    bind(sockfd, (struct sockaddr *)&sa, sizeof(sa));
    connfd = accept(sockfd, NULL, 0);

    /* 데이터 전송 — 커널이 sha256-ni(또는 최적 드라이버)로 처리 */
    write(connfd, data, len);

    /* 다이제스트 수신 */
    read(connfd, digest, 32);

    close(connfd);
    close(sockfd);
    return 0;
}

/* splice() zero-copy: 파일 해시를 커널 공간에서 직접 처리 */
int sha256_file_splice(int fd, unsigned char digest[32])
{
    /* ... socket/bind/accept 동일 ... */
    int pipefd[2];
    pipe(pipefd);

    /* 파일 → 파이프 → AF_ALG: 사용자 공간 복사 없음 */
    splice(fd, NULL, pipefd[1], NULL, file_size, 0);
    splice(pipefd[0], NULL, connfd, NULL, file_size, 0);

    read(connfd, digest, 32);
    /* ... */
}

대칭 암호 예제 (AES-CBC)

int aes_cbc_encrypt_af_alg(const void *key, int keylen,
    const void *iv, const void *pt, void *ct, int len)
{
    struct sockaddr_alg sa = {
        .salg_family = AF_ALG,
        .salg_type   = "skcipher",
        .salg_name   = "cbc(aes)",
    };
    int sockfd = socket(AF_ALG, SOCK_SEQPACKET, 0);
    bind(sockfd, (struct sockaddr *)&sa, sizeof(sa));
    setsockopt(sockfd, SOL_ALG, ALG_SET_KEY, key, keylen);

    int connfd = accept(sockfd, NULL, 0);

    /* cmsg로 IV와 operation(encrypt/decrypt) 전달 */
    struct msghdr msg = {};
    struct cmsghdr *cmsg;
    char cbuf[CMSG_SPACE(4) + CMSG_SPACE(16)];
    struct iovec iov = { .iov_base = (void *)pt, .iov_len = len };

    msg.msg_control = cbuf;
    msg.msg_controllen = sizeof(cbuf);
    msg.msg_iov = &iov;
    msg.msg_iovlen = 1;

    /* cmsg 1: operation = ALG_OP_ENCRYPT */
    cmsg = CMSG_FIRSTHDR(&msg);
    cmsg->cmsg_level = SOL_ALG;
    cmsg->cmsg_type  = ALG_SET_OP;
    cmsg->cmsg_len   = CMSG_LEN(4);
    *(__u32 *)CMSG_DATA(cmsg) = ALG_OP_ENCRYPT;

    /* cmsg 2: IV */
    cmsg = CMSG_NXTHDR(&msg, cmsg);
    cmsg->cmsg_level = SOL_ALG;
    cmsg->cmsg_type  = ALG_SET_IV;
    cmsg->cmsg_len   = CMSG_LEN(20);  /* 4(ivlen) + 16(iv) */
    struct af_alg_iv *aiv = (void *)CMSG_DATA(cmsg);
    aiv->ivlen = 16;
    memcpy(aiv->iv, iv, 16);

    sendmsg(connfd, &msg, 0);
    read(connfd, ct, len);

    close(connfd);
    close(sockfd);
    return 0;
}

AEAD 예제 (AES-GCM)

/* AF_ALG AEAD: AES-256-GCM 암호화 */
struct sockaddr_alg sa = {
    .salg_family = AF_ALG,
    .salg_type   = "aead",
    .salg_name   = "gcm(aes)",
};
int sockfd = socket(AF_ALG, SOCK_SEQPACKET, 0);
bind(sockfd, (struct sockaddr *)&sa, sizeof(sa));
setsockopt(sockfd, SOL_ALG, ALG_SET_KEY, key, 32);

/* 인증 태그 크기 설정 (16바이트) */
setsockopt(sockfd, SOL_ALG, ALG_SET_AEAD_AUTHSIZE, NULL, 16);

int connfd = accept(sockfd, NULL, 0);

/* cmsg에 ALG_SET_OP, ALG_SET_IV, ALG_SET_AEAD_ASSOCLEN 설정 */
/* sendmsg: [AAD (assoclen bytes)] + [plaintext] */
/* read:    [AAD (assoclen bytes)] + [ciphertext] + [tag (16 bytes)] */

/* cmsg 3: AAD 길이 */
cmsg->cmsg_type = ALG_SET_AEAD_ASSOCLEN;
cmsg->cmsg_len  = CMSG_LEN(4);
*(__u32 *)CMSG_DATA(cmsg) = aad_len;

/* iov[0] = AAD, iov[1] = plaintext */
sendmsg(connfd, &msg, 0);
/* 수신: AAD + ciphertext + 16바이트 GCM 태그 */
read(connfd, outbuf, aad_len + pt_len + 16);

AF_ALG 성능 비교

/proc/crypto와 드라이버 선택

# ━━━ /proc/crypto 활용법 ━━━

# 특정 알고리즘의 모든 구현 확인
awk '/^name.*cbc\(aes\)/,/^$/' /proc/crypto
# name         : cbc(aes)
# driver       : cbc-aes-aesni       priority: 400
# name         : cbc(aes)
# driver       : cbc-aes-generic     priority: 100

# AF_ALG에서 특정 드라이버 강제 지정
# salg_name에 드라이버 이름을 직접 사용
struct sockaddr_alg sa = {
    .salg_family = AF_ALG,
    .salg_type   = "skcipher",
    .salg_name   = "cbc-aes-aesni",  /* 드라이버 이름 직접 지정 */
};

# 전체 알고리즘 유형별 개수
grep '^type' /proc/crypto | sort | uniq -c | sort -rn
#  45 type         : skcipher
#  32 type         : shash
#  18 type         : aead
#   8 type         : ahash
#   5 type         : rng

구현 시 자주 틀리는 지점

알고리즘 선택은 맞는데 실제 동작이 깨지는 경우, 아래 항목 중 하나에 걸린 경우가 많습니다. 이 표는 Crypto API를 소비하는 코드 관점의 체크리스트입니다. 앞서 나온 "알고리즘 구현 체크리스트"와는 성격이 다릅니다.

관련 문서

Crypto Framework (Crypto API)와 관련된 다른 주제를 더 깊이 이해하고 싶다면 다음 문서를 참고하세요.

• 커널 보안 — 보안과 암호화
• ext4 — 파일 시스템 암호화
• 네트워크 보안 — IPsec, TLS
• 커널 모듈 — 모듈 서명 검증
• DPDK 암호화 가속 — DPDK cryptodev 프레임워크
• SmartNIC/DPU 암호화 오프로드 — IPsec/TLS 인라인 오프로드
• kTLS — 커널 TLS 하드웨어 오프로드
• IPsec & xfrm — IPsec 하드웨어 오프로드
• UFS 인라인 암호화 — UFS ICE 엔진
• 하드웨어 난수 생성기 — hwrng & QRNG
• OpenSSL — OpenSSL 3.x Provider 아키텍처와 커널 연동
• WireGuard — ChaCha20-Poly1305 VPN
• NAS HW 오프로드 — QAT 압축, SED/OPAL, 암호화 오프로드 종합
• 암호화 알고리즘 내부 구조 — AES, SHA-256, RSA, ECDSA 등 알고리즘 심층 분석
• 암호화 하드웨어 가속 — AES-NI, ARM CE, QAT, 가속기 디바이스, 오프로드
• 암호화 드라이버 구현 가이드 — 알고리즘 드라이버 구현, 등록, 테스트, 성능 추적

외부 참고 자료

• Kernel Crypto API — Documentation — 커널 암호화 프레임워크 공식 문서입니다
• Crypto API Introduction — Crypto API 개요 및 아키텍처 소개입니다
• Crypto API Architecture — Crypto API 내부 아키텍처 상세 문서입니다
• Developing Cipher Algorithms — 커널 암호 알고리즘 개발 가이드입니다
• Linux 커널 crypto/ 디렉토리 — 커널 암호화 서브시스템 소스 코드입니다
• x86 Crypto 가속 구현 — AES-NI, AVX2, SHA-NI 등 x86 하드웨어 가속 소스입니다
• AF_ALG — Linux man page — 사용자 공간에서 커널 Crypto API에 접근하는 소켓 인터페이스입니다
• Intel AES-NI — AES-NI 명령어 세트 기술 문서입니다
• NIST CAVP — 암호 알고리즘 검증 프로그램 (FIPS 인증 테스트)입니다
• LWN.net — Cryptography — LWN의 커널 암호화 관련 기사 인덱스입니다