Scatterlist in linux crypto api - linux

Question

I start to learn how to work with Crypto API in linux. It's offered to use scatterlist structures to transfer plaintext to block cipher function. Scatterlist handle to the plaintext by storing location of plaintext on the memmory page. Simplyfied definition of struct scatterlist is:
struct scatterlist {
unsigned long page_link; //number of virtual page in kernel space where data buffer is stored
unsigned int offset; //offset from page start address to data buffer start address
unsigned int length; //data buffer length
dma_addr_t dma_address; //i don't know the purpose of this variable at the moment
};
To get scatterlist variable which handle to plaintext buffer we use next function: void sg_init_one(struct scatterlist *, const void *, unsigned int);. To get buffer start address from scatterlist variable we use next function:void *sg_virt(struct scatterlist *sg).
For example:
#include <linux/init.h>
#include <linux/module.h>
#include <linux/crypto.h>
#include <linux/scatterlist.h>
u8 plaintext_global[16]={0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f};
static int __init simple_init (void){
u8 *ptr_to_local, *ptr_to_global;
u8 palintext_local[16]={0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f};
struct scatterlist sg[2];
sg_init_one(&sg[0], plaintext_local, 16);
sg_init_one(&sg[1], plaintext_global, 16);
printk("sg[0].page_link=%u\n", sg[0].page_link);
printk("sg[0].offset=%u\n", sg[0].offset);
printk("sg[0].length=%u\n", sg[0].length);
printk("sg[1].page_link=%u\n", sg[1].page_link);
printk("sg[1].offset=%u\n", sg[1].offset);
printk("sg[1].length=%u\n", sg[1].length);
ptr_to_local=sg_virt(&sg[0]);
ptr_to_global=sg_virt(&sg[1]);
printk("plaintext_local start address:%p\n", plaintext_local);
printk("sg_virt(&sg[0]):%p\n", ptr_to_local);
printk("plaintext_global start address:%p\n", plaintext_global);
printk("sg_virt(&sg[1]):%p\n", ptr_to_global);
}
And output in dmesg after insmod this module:
sg[0].page_link=31209922
sg[0].offset=3168
sg[0].length=16
sg[1].page_link=16853378
sg[1].offset=0
sg[1].length=16
plaintext_local start address:ffff8800770e7c60
sg_virt(&sg[0]):ffff8800770e7c60
plaintext_global start address:ffffffffc04a6000
sg_virt(&sg[1]):ffff8800404a6000
First question is why with local plaintext buffer sg_virt return the same value as local buffer address, but with global plaintext buffer return value of sg_virt have another prefix than global buffer address?
Next. Now I use crypto api:
#include <linux/init.h>
#include <linux/module.h>
#include <linux/crypto.h>
#include <linux/scatterlist.h>
u8 aes_in[]={0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88, 0x99, 0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0xff};
u8 aes_key[]={0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f};
u8 aes_out[]={0x69, 0xc4, 0xe0, 0xd8, 0x6a, 0x7b, 0x04, 0x30, 0xd8, 0xcd, 0xb7, 0x80, 0x70, 0xb4, 0xc5, 0x5a};
static int __init simple_init (void){
struct crypto_blkcipher *blk;
struct blkcipher_desc desc;
struct scatterlist sg[3];
u8 encrypted[100];
u8 decrypted[100];
blk=crypto_alloc_blkcipher("ecb(aes)",0,0);
crypto_blkcipher_setkey(blk, aes_key, 16);
sg_init_one(&sg[0], aes_in, 16);
sg_init_one(&sg[1], encrypted, 16);
sg_init_one(&sg[2], decrypted, 16);
desc.tfm=blk;
desc.flags=0;
sg_copy_from_buffer(&sg[0],1,aes_128_in, 16);
crypto_blkcipher_encrypt(&desc, &sg[1], &sg[0], 16);
crypto_blkcipher_decrypt(&desc, &sg[2], &sg[1], 16);
crypto_free_blkcipher(blk);
}
Encrypted data: 69 c4 e0 d8 6a 7b 04 30 d8 cd b7 80 70 b4 c5 5a
Decrypted data: 00 11 22 33 44 55 66 77 88 99 aa bb cc dd ee ff
Next question, what in detail did sg_copy_from_buffer function? Without this function encrypted data not right:
Encrypted data without sg_copy_from_buffer : 03 07 23 fc 20 11 42 c6 60 b3 36 07 eb c8 c9 62
Encrypted data without sg_copy_from_buffer : 00 00 00 00 00 00 00 00 58 51 02 a0 f7 7f 00 00

Answer 1

For your first question, the scatterlist saves the buffer you give it as a struct page internally(the "page link is actually a pointer to a struct page"), of which you can think as a physical address(Not exactly, but a struct page does represent a unique physical page).
That means scatterlist will first convert the buffer's virtual address to the corresponding physical address through sg_init_one, which finally calls the macro function ___pa to do that. When you call sg_virt, it will convert the physical address stored in the scatterlist back to a virtual address through another macro ___va.
Actually, ___pa is used to convert a virtual address within the linear mapping address range or in the kernel image address range to its corresponding physical address. ___va is used to convert a physical address to its corresponding virtual address within the linear mapping address range. They probably give a wrong output when converting an address out of aforementioned address ranges.
However, the global buffer you give to a scatterlist is within the kernel module address range which is behind the kernel image address range and the local buffer is within the kernel stack address range which is before the kernel image address range. Both of them are not within the kernel linear mapping address range, so after being converted through "___pa" and "___va", they are probably wrong.
According to your test, the local buffer address is right but the global buffer address is wrong, this is because the local buffer address is before the kernel image address range and the global buffer address is after the kernel image address range, so they are converted in a different way in "__pa" but in the same way in "___va". You can see it from the following code snippet in linux kernel source code /arch/x86/include/asm/page.h and
/arch/x86/include/asm/page_64.h.
// This function is the implementation of ___pa on x86-64
static inline unsigned long __phys_addr_nodebug(unsigned long x)
{
// __START_KERNEL_map is the start address of the kernel image address range.
unsigned long y = x - __START_KERNEL_map;
// You can see that this function behaves differently depending on x and __START_KERNEL_map
/* use the carry flag to determine if x was < __START_KERNEL_map */
// phys_base is the start of system's physical address
// PAGE_OFFSET is the start of linear mapping address range
x = y + ((x > y) ? phys_base : (__START_KERNEL_map - PAGE_OFFSET));
return x;
}
// This is the implementation of ___va on x86-64
#define __va(x) ((void *)((unsigned long)(x)+PAGE_OFFSET))
For a virtual address before the kernel image address range, ___va just adds an offset and ___pa just subtracts the same offset, so the local buffer address is right. However, for a virtual address after the kernel image address, ___va does the same work but ___pa behaves differently, so the global buffer address is wrong.
For x86-64 linux kernel memory layout, please refer to linux source code at Documentation/x86/x86_64/mm.rst
Note that only the buffer allocated by kmalloc will stay in the kernel linear mapping address range, so you should always use kmalloc to allocate memory for linux kernel crypto operations.
For your second question, a scatterlist can be made of a single struct scatterlist. However it is actually designed for managing a list of memory chunks, and every chunk is represented by a struct scatterlist. Using sg_copy_from_buffer, you can copy the data stored in a continuous buffer to a list of memory chunks managed by several struct scatterlists. In short, sg_copy_from_buffer has no concern with encryption.
For more details, please refer to the following kernel source code files.
/include/linux/scatterlist.h
/lib/scatterlist.c
/arch/x86/include/asm/page.h
/arch/x86/include/asm/page_64.h