Kerberos V Cryptography API

Kerberos V Cryptography API와 목차

SPDX 라이선스 식별자: GPL-2.0

Kerberos V Cryptography API

목차

• 개요
• 개요 > 작은 buffer
• encoding type
• key derivation
• key derivation > PRF+ 계산
• key derivation > Kc, Ke, Ki 유도
• crypto 함수
• crypto 함수 > 준비 함수
• crypto 함수 > encryption mode
• crypto 함수 > checksum mode
• `krb5enc` AEAD 알고리즘

개요

개요

이 API는 network filesystem에서 사용할 key derivation, encryption, checksum 계산을 위해 Kerberos 5 방식의 암호 기능을 제공하며, GSSAPI에 필요한 low-level crypto를 구현하는 데 사용할 수 있습니다.

다음 crypto type을 지원합니다.

KRB5_ENCTYPE_AES128_CTS_HMAC_SHA1_96
KRB5_ENCTYPE_AES256_CTS_HMAC_SHA1_96
KRB5_ENCTYPE_AES128_CTS_HMAC_SHA256_128
KRB5_ENCTYPE_AES256_CTS_HMAC_SHA384_192
KRB5_ENCTYPE_CAMELLIA128_CTS_CMAC
KRB5_ENCTYPE_CAMELLIA256_CTS_CMAC

KRB5_CKSUMTYPE_HMAC_SHA1_96_AES128
KRB5_CKSUMTYPE_HMAC_SHA1_96_AES256
KRB5_CKSUMTYPE_CMAC_CAMELLIA128
KRB5_CKSUMTYPE_CMAC_CAMELLIA256
KRB5_CKSUMTYPE_HMAC_SHA256_128_AES128
KRB5_CKSUMTYPE_HMAC_SHA384_192_AES256

다음과 같이 API header를 포함할 수 있습니다.

#include <crypto/krb5.h>

작은 buffer

작은 buffer

key와 같은 작은 데이터 조각을 전달하기 위해 데이터 pointer와 데이터 크기를 담는 buffer 구조체를 정의합니다.

struct krb5_buffer {
        unsigned int        len;
        void                *data;
};

encoding type 구조체

encoding type

encoding type은 다음 구조체로 정의합니다.

struct krb5_enctype {
        int                etype;
        int                ctype;
        const char        *name;
        u16                key_bytes;
        u16                key_len;
        u16                Kc_len;
        u16                Ke_len;
        u16                Ki_len;
        u16                prf_len;
        u16                block_len;
        u16                conf_len;
        u16                cksum_len;
        ...
};

encoding type 필드와 조회

API 사용자가 주목해야 할 필드는 다음과 같습니다.

• `etype`과 `ctype`은 각각 encryption과 checksum 계산에 쓰는 이 encoding type의 protocol 번호를 나타냅니다. 값으로 `KRB5_ENCTYPE_*` 및 `KRB5_CKSUMTYPE_*` 상수를 담습니다.
• `name`은 encoding의 공식 이름입니다.
• `key_len`과 `key_bytes`는 각각 입력 key 길이와 유도된 key 길이입니다. 둘은 여기서 지원하지 않는 DES에서만 다른 것으로 보입니다.
• `Kc_len`, `Ke_len`, `Ki_len`은 유도된 Kc, Ke, Ki key의 크기입니다. Kc는 checksum mode에서 사용하고 Ke와 Ki는 encryption mode에서 사용합니다.
• `prf_len`은 PRF+ 함수 계산 결과의 크기입니다.
• `block_len`, `conf_len`, `cksum_len`은 각각 encryption block 길이, confounder 길이, checksum 길이입니다. 세 값 모두 encryption mode에서 사용하지만 checksum mode에서는 checksum 길이만 사용합니다.

encoding type은 다음 함수로 번호를 이용해 조회합니다.

const struct krb5_enctype *crypto_krb5_find_enctype(u32 enctype);

key derivation과 PRF+ 계산

key derivation

application이 encryption type을 선택하면 실제 crypto에 사용할 key를 transport key로부터 유도할 수 있습니다.

PRF+ 계산

key derivation을 돕기 위해 Kerberos GSSAPI mechanism의 PRF+를 계산하는 함수를 제공합니다.

int crypto_krb5_calc_PRFplus(const struct krb5_enctype *krb5,
                             const struct krb5_buffer *K,
                             unsigned int L,
                             const struct krb5_buffer *S,
                             struct krb5_buffer *result,
                             gfp_t gfp);

이 함수는 source key와 그 용도를 제한하는 추가 데이터로부터 transport key를 유도하는 데 사용할 수 있습니다.

crypto 함수와 message buffer 배치

crypto 함수

key를 유도한 뒤에는 데이터에 crypto 연산을 수행할 수 있습니다. 전송할 message를 준비할 때 caller는 confounder가 필요하다면 이를 저장할 공간과 checksum을 저장할 공간을 buffer에 비워 두어야 합니다. 이를 돕는 enum과 함수 두 개를 제공합니다.

enum krb5_crypto_mode {
        KRB5_CHECKSUM_MODE,
        KRB5_ENCRYPT_MODE,
};

size_t crypto_krb5_how_much_buffer(const struct krb5_enctype *krb5,
                                   enum krb5_crypto_mode mode,
                                   size_t data_size, size_t *_offset);

size_t crypto_krb5_how_much_data(const struct krb5_enctype *krb5,
                                 enum krb5_crypto_mode mode,
                                 size_t *_buffer_size, size_t *_offset);

이 함수들은 모두 encoding type과 crypto mode가 checksum 전용인지 full encryption인지 나타내는 값을 받습니다.

buffer 크기와 data 위치 확인

첫 번째 함수는 주어진 양의 데이터를 담는 데 필요한 buffer 크기를 반환합니다. 두 번째 함수는 특정 크기의 buffer에 들어갈 데이터 양을 반환하고 필요한 buffer 크기를 그에 맞게 줄여 조정합니다. 두 경우 모두 buffer 안에서 데이터가 시작되는 offset도 반환합니다.

message를 수신한 뒤에는 다음 함수를 호출해 message 안의 데이터 위치와 크기를 판별할 수 있습니다.

int crypto_krb5_where_is_the_data(const struct krb5_enctype *krb5,
                                  enum krb5_crypto_mode mode,
                                  size_t *_offset, size_t *_len);

caller는 message의 offset과 길이를 함수에 제공하며, 함수는 이 값을 데이터와 padding이 들어 있는 영역을 나타내도록 변경합니다. padding 양은 caller가 판별해야 합니다. 길이가 너무 짧거나 mode를 지원하지 않으면 함수가 error를 반환합니다. 다음 추가 함수도 제공합니다.

int crypto_krb5_check_data_len(const struct krb5_enctype *krb5,
                               enum krb5_crypto_mode mode,
                               size_t len, size_t min_content);

이 함수는 decrypted 또는 verified message가 충분한 최소 payload를 포함하는지만 기본적으로 검사합니다.

crypto 객체 준비 함수

준비 함수

action 함수에서 사용할 crypto 객체를 할당하고 준비하는 함수 두 개를 제공합니다.

struct crypto_aead *
crypto_krb5_prepare_encryption(const struct krb5_enctype *krb5,
                               const struct krb5_buffer *TK,
                               u32 usage, gfp_t gfp);
struct crypto_shash *
crypto_krb5_prepare_checksum(const struct krb5_enctype *krb5,
                             const struct krb5_buffer *TK,
                             u32 usage, gfp_t gfp);

두 함수 모두 encoding type, transport key, 적절한 subkey를 유도하는 데 쓰는 usage 값을 받습니다. 함수는 encryption용 AEAD template 또는 checksum 계산용 synchronous hash에 해당하는 crypto 객체를 만들고, key를 설정한 뒤 객체를 구성합니다. caller는 반환된 handle을 아래 action 함수에 전달해야 합니다.

encryption mode API

encryption mode

message를 encrypt하고 decrypt하는 함수 한 쌍을 제공합니다.

ssize_t crypto_krb5_encrypt(const struct krb5_enctype *krb5,
                            struct crypto_aead *aead,
                            struct scatterlist *sg, unsigned int nr_sg,
                            size_t sg_len,
                            size_t data_offset, size_t data_len,
                            bool preconfounded);
int crypto_krb5_decrypt(const struct krb5_enctype *krb5,
                        struct crypto_aead *aead,
                        struct scatterlist *sg, unsigned int nr_sg,
                        size_t *_offset, size_t *_len);

두 경우 모두 같은 scatterlist로 입력 buffer와 출력 buffer를 지정합니다.

encryption과 decryption 동작

encryption 함수에서는 출력 buffer가 필요한 것보다 클 수 있으며 생성된 출력의 양이 반환됩니다. 데이터의 위치와 크기도 지정해야 하고 이는 encoding과 일치해야 합니다. confounder가 설정되지 않았다면 함수가 하나를 삽입합니다.

decryption 함수에는 buffer 안 message의 offset과 길이를 제공하며, 함수는 이 값을 실제 데이터에 맞게 줄입니다. decryption 함수는 message 안의 checksum도 검증하고 일치하지 않으면 error를 반환합니다.

checksum mode API

checksum mode

message의 checksum을 생성하고 그 checksum을 검증하는 함수 한 쌍을 제공합니다.

ssize_t crypto_krb5_get_mic(const struct krb5_enctype *krb5,
                            struct crypto_shash *shash,
                            const struct krb5_buffer *metadata,
                            struct scatterlist *sg, unsigned int nr_sg,
                            size_t sg_len,
                            size_t data_offset, size_t data_len);
int crypto_krb5_verify_mic(const struct krb5_enctype *krb5,
                           struct crypto_shash *shash,
                           const struct krb5_buffer *metadata,
                           struct scatterlist *sg, unsigned int nr_sg,
                           size_t *_offset, size_t *_len);

두 경우 모두 같은 scatterlist로 입력 buffer와 출력 buffer를 지정합니다. 추가 metadata를 전달할 수 있으며, 이는 데이터보다 먼저 hash에 추가됩니다.

checksum 생성과 검증 동작

`get_mic` 함수에서는 출력 buffer가 필요한 것보다 클 수 있으며 생성된 출력의 양이 반환됩니다. 데이터의 위치와 크기도 지정해야 하고 이는 encoding과 일치해야 합니다.

검증 함수에는 buffer 안 message의 offset과 길이를 제공하며, 함수는 이 값을 데이터에 맞게 줄입니다. checksum이 일치하지 않으면 error를 반환합니다.

krb5enc AEAD 알고리즘

`krb5enc` AEAD 알고리즘

"krb5enc"라는 template AEAD crypto 알고리즘을 제공합니다. 이 알고리즘은 plaintext를 hash한 다음 encrypt하며, 이는 authenc와 반대 순서입니다. `crypto_krb5_prepare_encryption()`이 반환하는 handle이 이 유형일 수 있지만, 이 API의 사용자가 직접 상호 작용해야 할 필요는 없습니다.

참고로 key format은 format 번호의 BE32로 시작합니다. 제공되는 것은 format 1뿐이며, 이어서 Ke key 길이의 BE32, Ki key 길이의 BE32, Ke key byte, Ki key byte 순서로 구성됩니다.

특정 순서로 정렬된 word를 사용하므로 static test data에는 byteswapping이 필요하지 않습니다.