Barebox · source analysis

Barebox FIT configuration과 검증

FIT configuration을 연 뒤 verify mode에 따른 서명 확인과 참조 image hash 확인이 언제 일어나는지 읽습니다.

Barebox v2026.06.1 common/image-fit.c를 분석 기준으로 삼는다. FIT 서명 검사, downgrade 방지, boot 후보 fallback은 각각 별도 정책 경계에서 확인한다.

Series
18 / 19
Baseline
v2026.06.1
Commit
314c679eea2d
Source
common/image-fit.c:1161-1249 (발췌 범위)

configuration 서명과 참조 image hash는 어떤 순서로 확인하는가?

fit_open_configuration()은 configuration을 선택한 뒤 fit_config_verify_signature()를 호출한다. 그 다음 호출자가 configuration cookie를 fit_open_image()에 넘겨 참조 image를 열 때 fit_verify_hash()를 호출한다.

이 호출 순서가 항상 두 검증을 수행한다는 뜻은 아니다. CONFIG_FITIMAGE_SIGNATURE와 handle->verify가 서명·hash의 실행 여부와 누락 시 오류 여부를 결정한다.

범위

이 페이지는 고정 common/image-fit.c의 FIT API를 설명한다. 서명 자체로 이전의 유효한 image를 거부하거나 전체 boot 후보의 fallback을 막는다고 단정하지 않는다.

FIT handle에서 반환 data까지

그림 1. configuration 검증과 image 반환에 쓰는 객체
입력선택·검증반환
01fit_handle: FIT·size·verify
02선택한 configuration node
03참조 image node의 data
04outdata·outsize
경계

configuration cookie가 있으면 image hash 경로, 없으면 개별 image signature 경로로 분기한다.

고정 image-fit.c의 API 객체를 나타낸다. 주소 예약이나 실제 부팅은 이 그림의 반환 data만으로 증명되지 않는다.

선택 뒤 서명, image 열 때 hash

그림 2. configuration cookie를 사용하는 호출 경로
fit_open() / fit_do_open()
configuration 선택
mode별 configuration signature
fit_open_image()의 hash
decompress·data 반환

서명 검증을 시도하는 과정에서 configuration이 참조한 image/hash node 목록을 먼저 구성한다. 자동 configuration 선택은 호환성 판단을 위해 FDT의 data를 읽을 수도 있지만, 참조 image의 payload hash 검증은 fit_open_image()에서 나중에 일어난다.

verify mode가 바꾸는 검사 조건

configuration 서명과 image hash는 서로 다른 조건으로 실행된다.

modeconfiguration signatureconfiguration cookie가 있는 image hash누락 시 동작
BOOTM_VERIFY_NONE생략생략이 두 검사로는 거부하지 않음
BOOTM_VERIFY_HASH생략hash-1/hash@1 검사image hash가 없으면 오류
BOOTM_VERIFY_SIGNATURE서명 node 필수·검증image hash 필수·검증단, 서명 기능 미빌드면 configuration 서명 함수는 성공 반환
BOOTM_VERIFY_AVAILABLE있으면 검증있으면 검증없는 서명/hash 자체는 허용; 존재한 검증의 실패는 오류

CONFIG_FITIMAGE_SIGNATURE가 꺼져 있으면 configuration 서명 함수는 mode와 관계없이 0을 반환한다. image hash 함수의 mode 분기는 별개다. configuration cookie 없이 fit_open_image()를 호출하면 개별 image signature 경로로 바뀐다.

검증의 순서와 정책의 범위를 나눠 보기

그림 3은 configuration cookie가 있는 API 경로다. 생략 가능한 검사에는 빌드 옵션과 verify mode를 명시했다.

그림 3. configuration signature 뒤에 참조 image hash

실제 호출은 fit_open_configuration() → fit_open_image() 순서다.

01FIT 열기·node parse
02configuration 선택
03mode별 configuration signature
04참조 image·data 얻기
05mode별 image hash
06decompress·data 반환
그림 4. hash·signature가 확인하는 것과 별도 boot 정책

서명 검증의 성공은 rollback·fallback 정책의 성공 증거가 아니다.

Image hash

01data byte의 digest 대조

02configuration cookie가 있는 image 경로

03NONE은 생략, AVAILABLE은 선택적

04HASH·SIGNATURE mode는 hash 필요

05hash만으로 출처 인증은 불가

Configuration signature

01참조·image/hash node metadata 결속

02빌드 옵션과 verify mode의 조건부 단계

03fit keyring의 공개키로 검증

04이전의 유효한 서명 image도 통과 가능

05전체 boot 후보 fallback은 별도 정책

원본 코드

아래 코드는 Barebox v2026.06.1의 common/image-fit.c에서 1161-1249줄을 그대로 가져온 것이다.

commit314c679eea2d0ca847c64d1b646a1cf91225c0ecanchor · L1185static int do_bootm_fit(struct image_data *data)
1161}
1162
1163static bool __fit_close(struct fit_handle *handle)
1164{
1165	if (!refcount_dec_and_test(&handle->users))
1166		return false;
1167
1168	if (handle->root)
1169		of_delete_node(handle->root);
1170
1171	if (handle->filename)
1172		list_del(&handle->entry);
1173
1174	free(handle->filename);
1175	free(handle->fit_alloc);
1176	return true;
1177}
1178
1179void fit_close(struct fit_handle *handle)
1180{
1181	if (__fit_close(handle))
1182		free(handle);
1183}
1184
1185static int do_bootm_fit(struct image_data *data)
1186{
1187	pr_err("Cannot boot device tree binary blob\n");
1188
1189	return -EINVAL;
1190}
1191
1192static bool fitimage_check(struct image_handler *handler,
1193			   struct image_data *data,
1194			   enum filetype detected_filetype)
1195{
1196	return detected_filetype == filetype_oftree ||
1197		detected_filetype == filetype_fit;
1198}
1199
1200static struct image_handler fit_handler = {
1201	.name = "FIT image",
1202	.bootm = do_bootm_fit,
1203	.filetype = filetype_fit,
1204	.check_image = fitimage_check,
1205};
1206
1207static int bootm_fit_register(void)
1208{
1209	return register_image_handler(&fit_handler);
1210}
1211late_initcall(bootm_fit_register);
1212
1213static int fuzz_fit(const u8 *data, size_t size)
1214{
1215	const char *unit, *imgname = "kernel";
1216	struct fit_handle handle = {};
1217	const void *outdata;
1218	unsigned long outsize, addr;
1219	int ret;
1220	void *config;
1221
1222	handle.verbose = false;
1223	handle.verify = BOOTM_VERIFY_AVAILABLE;
1224
1225	handle.size = size;
1226	handle.fit = data;
1227	handle.fit_alloc = NULL;
1228
1229	refcount_set(&handle.users, 1);
1230
1231	ret = fit_do_open(&handle);
1232	if (ret)
1233		goto out;
1234
1235	config = fit_open_configuration(&handle, NULL, NULL);
1236	if (IS_ERR(config)) {
1237		ret = fit_find_last_unit(&handle, &unit);
1238		if (ret)
1239			goto out;
1240		config = fit_open_configuration(&handle, unit, NULL);
1241	}
1242	if (IS_ERR(config)) {
1243		ret = PTR_ERR(config);
1244		goto out;
1245	}
1246
1247	ret = fit_open_image(&handle, config, imgname, 0, &outdata, &outsize);
1248	if (ret)
1249		goto out;

두 발췌가 보여 주는 범위

첫 발췌의 do_bootm_fit()은 “Cannot boot device tree binary blob”을 출력하고 -EINVAL을 반환한다. 이 함수를 성공적인 load/handoff 구현으로 읽으면 안 된다.

관련 발췌의 configuration 자동 선택은 호환성 판단에 FDT data를 읽을 수 있다. 서명과 image hash의 mode 분기·실행 순서는 고정 원문의 fit_open_configuration(), fit_config_verify_signature(), fit_open_image()를 이어 읽는다.

fit_open()은 같은 canonical filename의 열린 핸들이 있으면 참조 수만 늘려 반환한다(L1101–1105). 이 경로는 새 verify·verbose 인자를 기존 핸들에 다시 설정하지 않는다. 따라서 호출 인자뿐 아니라 반환된 handle->verify와 기존 핸들의 수명도 확인한다. 또한 ramdisk는 compression 속성이 있어도 이 helper에서 압축 해제를 건너뛰는 예외다.

함께 읽어야 하는 원본 코드

첫 코드 조각만으로 동작이 완성되지 않는 경우 호출 매크로, 객체 정의와 실제 실행 목록을 같은 페이지에 묶었다. 각 조각은 같은 기준 commit에서 가져왔다.

01. configuration 서명 검사와 FDT 호환성 선택

common/image-fit.c 778-862줄이다.

filecommon/image-fit.canchor · L788int fit_config_verify_signature
778	ret = fit_handle_decompression(image, type, &data, &data_len);
779	if (ret)
780		return ret;
781
782	*outdata = data;
783	*outsize = data_len;
784
785	return 0;
786}
787
788int fit_config_verify_signature(struct fit_handle *handle, struct device_node *conf_node)
789{
790	struct device_node *sig_node;
791	int ret = -EINVAL;
792
793	if (!IS_ENABLED(CONFIG_FITIMAGE_SIGNATURE))
794		return 0;
795
796	switch (handle->verify) {
797	case BOOTM_VERIFY_NONE:
798	case BOOTM_VERIFY_HASH:
799		return 0;
800	case BOOTM_VERIFY_SIGNATURE:
801		ret = -EINVAL;
802		break;
803	case BOOTM_VERIFY_AVAILABLE:
804		ret = 0;
805		break;
806	}
807
808	for_each_child_of_node(conf_node, sig_node) {
809		if (!of_node_has_prefix(sig_node, "signature"))
810			continue;
811
812		if (handle->verbose)
813			of_print_nodes(sig_node, 0, ~0);
814
815		ret = fit_verify_signature(handle, sig_node, conf_node);
816		if (ret < 0)
817			return ret;
818	}
819
820	if (ret < 0) {
821		pr_err("configuration '%pOF' does not have a signature\n", conf_node);
822		return ret;
823	}
824
825	return ret;
826}
827
828static int fit_fdt_is_compatible(struct fit_handle *handle,
829				 struct device_node *child,
830				 const char *machine)
831{
832	const char *reason = "malformed";
833	struct device_node *image;
834	const char *unit = "fdt";
835	int data_len;
836	const void *data;
837	int ret;
838
839	if (of_property_present(child, "compatible"))
840		return 0;
841	if (!of_property_present(child, "fdt"))
842		return 0;
843
844	image = fit_get_image(handle, child, &unit, 0);
845	if (!image) {
846		ret = -ENOENT;
847		goto err;
848	}
849
850	data = of_get_property(image, "data", &data_len);
851	if (!data)
852		goto err;
853
854	/* We have three options here:
855	 *
856	 * 1) Increase our attack surface by all supported compression algos
857	 * 2) Verify all configurations in the image as we search for best
858	 *    OF match score
859	 * 3) Blame the user and expect them to supply a compatible property
860	 *    in the configuration node if they want to compress their FDTs
861	 *
862	 * We go for option 3.

고정 FIT API의 단계별 결과

01

FIT handle과 configuration을 연다

fit_open()은 open_fdt()로 파일을 열어 buffer를 읽고 fit_do_open()에서 tree를 unflatten한다. fit_open_configuration()은 명시 이름 또는 compatible/default 선택으로 configuration node를 찾는다. 자동 선택 중에는 FDT data가 호환성 점수에 쓰일 수 있다.

02

서명 함수 호출과 실제 수행을 구분한다

선택 뒤 fit_config_verify_signature()를 호출한다. 서명 기능 미빌드 또는 NONE/HASH mode면 0으로 건너뛴다. SIGNATURE mode는 서명 node 부재를 오류로, AVAILABLE mode는 부재를 허용하되 존재한 서명이 실패하면 오류로 처리한다.

03

서명이 포함하는 node 목록을 계산한다

fit_config_build_hash_nodes()는 configuration property가 참조하는 image node와 hash child node를 목록에 넣는다. fit_verify_signature()는 data property를 digest에서 제외하고 이 metadata에 대한 서명을 fit keyring의 공개키로 확인한다. payload byte는 이후 image hash가 다룬다.

04

참조 image를 열며 hash를 확인한다

configuration cookie가 있으면 fit_open_image()는 참조 image의 data property를 읽고 fit_verify_hash()를 호출한다. 이 함수는 hash-1/hash@1 node를 찾아 byte digest를 비교한다. 성공한 뒤 필요하면 decompress하여 outdata와 outsize를 반환한다.

05

부팅 정책은 API 반환 바깥이다

configuration cookie 없이 image를 열면 hash 대신 개별 image signature 경로로 간다. 이 파일의 do_bootm_fit()은 -EINVAL을 반환하므로 그림의 반환 data를 곧바로 bootm handoff·주소 예약·실행 성공으로 표현하지 않는다.

서명 통과 뒤에도 남는 정책 경계

01

verify mode와 빌드 옵션을 함께 고정한다

CONFIG_FITIMAGE_SIGNATURE가 없으면 configuration 서명 함수는 SIGNATURE mode에서도 0을 반환한다. 반면 configuration cookie가 있는 image hash는 별도 handle->verify 분기를 따른다. 빌드 config와 실제 API 인자를 함께 기록해야 강제 범위를 알 수 있다.

02

외부 data 범위를 실행 단계로 추정하지 않는다

fit_open_image()에는 data-offset/data-position를 읽는 단계가 없고 of_get_property(image, "data", ...)가 보인다. 외부 payload를 허용하는 제품 경로라면 file parser·buffer 경계와 hash 대상 byte를 별도 소스로 추적한다.

03

rollback과 fallback은 별도로 검증한다

유효한 과거 FIT 서명도 key와 서명 검증만으로 거부되지 않는다. 신뢰 가능한 버전·counter 및 다른 boot 후보로 넘어가는 상위 경로의 정책이 필요하다. 이 함수의 성공·실패 반환만으로 required key 강제나 모든 fallback 차단을 보증하지 않는다.

검증에 쓰는 node와 반환 data

대상출처사용 시점확인할 경계
fit_handlefit_open()/fit_open_buf()FIT tree·size·verify mode 보유호출자가 넘긴 mode와 실제 빌드 옵션
configuration nodefit_open_configuration()선택 뒤 서명 함수 입력·image 참조명시/자동 선택과 서명 결과
image data·hash nodefit_get_image()/of_get_property()hash 또는 개별 signature 후 decompressconfiguration cookie 유무와 byte 일치
outdata·outsizefit_open_image() 반환호출자 소비 전까지 FIT handle에 연계적재·실행 정책은 호출자에서 추적

이 API의 오류와 별도 정책 실패

상황고정 코드 동작별도 확인
configuration을 찾지 못함ERR_PTR(-ENOENT) 등 반환상위 후보 선택 정책
SIGNATURE mode의 signature node 부재기능 빌드 시 configuration 열기 실패빌드 config와 mode
필수 image hash 부재 또는 digest 불일치hash 함수가 오류 반환configuration cookie와 실제 byte
이전 버전이지만 유효한 서명이 코드에는 rollback counter 비교가 없음신뢰된 단조 버전 정책
검증 후 다른 후보 선택이 함수의 반환만으로 차단 여부를 알 수 없음호출자·bootm 상위 흐름

실제 빌드에서 대조할 자료

고정 원문과 제품의 소스·config·boot 경로를 읽기 전용으로 비교한다.

목적읽기 전용 자료판정 기준
mode와 빌드 gate제품 .config의 CONFIG_FITIMAGE_SIGNATURE, 호출자의 verify 인자서명 누락이 실패하는 구성인지 확인
검증 순서fit_open_configuration()와 fit_open_image() 호출 지점configuration cookie 전달과 오류 처리 확인
payload bytesFIT image node의 data, hash-1와 실제 반환 data검증 전 data와 decompress 후 data 구분
rollback·fallback제품 counter 저장소, boot 후보 반복/handler 전환 코드이 파일 바깥의 강제 근거 확인

복구 가능한 시험 환경에서 확인

  1. 01
    mode별 누락 조건

    NONE/HASH/SIGNATURE/AVAILABLE 모드와 서명 node 유무를 바꾸어 fit_open_configuration() 반환을 기록한다. 빌드 옵션도 함께 기록한다.

  2. 02
    참조 image 한 byte 변경

    configuration cookie를 유지한 fit_open_image() 호출에서 hash 실패 여부를 확인한다. configuration signature 통과 여부와 별도 기록한다.

  3. 03
    과거 서명과 fallback 후보

    제품의 신뢰된 버전 counter·상위 boot 후보 정책을 이용해 과거의 유효 서명 FIT 및 실패 후 다른 후보 시도를 각각 시험한다.

원문과 다음 글