커널 Crypto API 인터페이스 명세 | Linux 6.18.37

요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.

1. 요약·해설

원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.

요약과 해설

intro.rst:1-74

이 문서는 커널 Crypto API 전체를 읽기 위한 용어와 객체 관계를 정리합니다. 알고리즘은 transformation 구현체로 등록되고, consumer가 이를 요청하면 개별 transformation 객체(TFM)를 담은 cipher handle이 만들어집니다.

실제 사용 흐름은 handle 초기화, handle을 전달하는 연산 실행, handle 파괴의 세 단계입니다. 암호화뿐 아니라 CRC와 압축 같은 transformation도 같은 모델에 들어오며, 초기화 함수는 `crypto_alloc\*` 이름 규칙을 따릅니다.

2. 영어 원문 전체

번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.

원문 전체 펼치기

1 Kernel Crypto API Interface Specification

2 =========================================

4 Introduction

5 ------------

7 The kernel crypto API offers a rich set of cryptographic ciphers as well

8 as other data transformation mechanisms and methods to invoke these.

9 This document contains a description of the API and provides example

10 code.

12 To understand and properly use the kernel crypto API a brief explanation

13 of its structure is given. Based on the architecture, the API can be

14 separated into different components. Following the architecture

15 specification, hints to developers of ciphers are provided. Pointers to

16 the API function call documentation are given at the end.

18 The kernel crypto API refers to all algorithms as "transformations".

19 Therefore, a cipher handle variable usually has the name "tfm". Besides

20 cryptographic operations, the kernel crypto API also knows compression

21 transformations and handles them the same way as ciphers.

23 The kernel crypto API serves the following entity types:

25 - consumers requesting cryptographic services

27 - data transformation implementations (typically ciphers) that can be

28 called by consumers using the kernel crypto API

30 This specification is intended for consumers of the kernel crypto API as

31 well as for developers implementing ciphers. This API specification,

32 however, does not discuss all API calls available to data transformation

33 implementations (i.e. implementations of ciphers and other

34 transformations (such as CRC or even compression algorithms) that can

35 register with the kernel crypto API).

37 Note: The terms "transformation" and cipher algorithm are used

38 interchangeably.

40 Terminology

41 -----------

43 The transformation implementation is an actual code or interface to

44 hardware which implements a certain transformation with precisely

45 defined behavior.

47 The transformation object (TFM) is an instance of a transformation

48 implementation. There can be multiple transformation objects associated

49 with a single transformation implementation. Each of those

50 transformation objects is held by a crypto API consumer or another

51 transformation. Transformation object is allocated when a crypto API

52 consumer requests a transformation implementation. The consumer is then

53 provided with a structure, which contains a transformation object (TFM).

55 The structure that contains transformation objects may also be referred

56 to as a "cipher handle". Such a cipher handle is always subject to the

57 following phases that are reflected in the API calls applicable to such

58 a cipher handle:

60 1. Initialization of a cipher handle.

62 2. Execution of all intended cipher operations applicable for the handle

63 where the cipher handle must be furnished to every API call.

65 3. Destruction of a cipher handle.

67 When using the initialization API calls, a cipher handle is created and

68 returned to the consumer. Therefore, please refer to all initialization

69 API calls that refer to the data structure type a consumer is expected

70 to receive and subsequently to use. The initialization API calls have

71 all the same naming conventions of crypto_alloc\*.

73 The transformation context is private data associated with the

74 transformation object.

3. 한국어 전문 번역

영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.

커널 Crypto API 인터페이스 명세와 소개

1-10

커널 Crypto API 인터페이스 명세

소개

커널 Crypto API는 풍부한 암호화 cipher 집합뿐 아니라 다른 데이터 변환 메커니즘과 이를 호출하는 방법도 제공합니다. 이 문서는 API를 설명하고 예제 코드를 제공합니다.

구조와 transformation

11-22

커널 Crypto API를 이해하고 올바르게 사용할 수 있도록 그 구조를 간략히 설명합니다. 아키텍처에 따라 API를 여러 구성 요소로 나눌 수 있습니다. 아키텍처 명세에 이어 cipher 개발자를 위한 지침을 제공하며, 마지막에는 API 함수 호출 문서를 가리키는 참조를 제시합니다.

커널 Crypto API는 모든 알고리즘을 "transformation"이라고 부릅니다. 따라서 cipher handle 변수의 이름은 일반적으로 `tfm`입니다. 커널 Crypto API는 암호 연산 외에도 압축 transformation을 인식하며 cipher와 같은 방식으로 처리합니다.

서비스 대상과 명세 범위

23-38

커널 Crypto API는 다음 유형의 entity에 서비스를 제공합니다.

암호화 서비스를 요청하는 consumer
커널 Crypto API를 사용하는 consumer가 호출할 수 있는 데이터 transformation 구현체(일반적으로 cipher)

이 명세는 커널 Crypto API의 consumer와 cipher 구현 개발자를 대상으로 합니다. 그러나 데이터 transformation 구현체, 즉 커널 Crypto API에 등록할 수 있는 cipher 및 기타 transformation(CRC나 압축 알고리즘 등)에 제공되는 모든 API 호출을 다루지는 않습니다.

참고: 이 문서에서는 "transformation"과 cipher 알고리즘이라는 용어를 서로 바꾸어 사용합니다.

용어: transformation 구현체

39-45

용어

transformation 구현체는 정확히 정의된 동작에 따라 특정 transformation을 구현하는 실제 코드 또는 hardware 인터페이스입니다.

용어: transformation 객체

46-54

transformation 객체(TFM)는 transformation 구현체의 instance입니다. 하나의 transformation 구현체에 여러 transformation 객체가 연결될 수 있습니다. 각 객체는 Crypto API consumer 또는 다른 transformation이 보유합니다. Crypto API consumer가 transformation 구현체를 요청하면 transformation 객체가 할당되며, consumer는 transformation 객체(TFM)를 포함하는 구조체를 전달받습니다.

cipher handle의 생명 주기

55-66

transformation 객체를 포함하는 구조체를 "cipher handle"이라고 부르기도 합니다. 이러한 cipher handle에는 관련 API 호출에 반영된 다음 단계가 항상 적용됩니다.

cipher handle을 초기화합니다.
해당 handle에 필요한 모든 cipher 연산을 실행합니다. 이때 모든 API 호출에 cipher handle을 제공해야 합니다.
cipher handle을 파괴합니다.

초기화 호출과 transformation context

67-74

초기화 API 호출을 사용하면 cipher handle이 생성되어 consumer에게 반환됩니다. 따라서 consumer가 전달받아 이후 사용할 데이터 구조체 유형을 언급하는 모든 초기화 API 호출을 참조하십시오. 초기화 API 호출은 모두 `crypto_alloc\*`라는 동일한 이름 규칙을 따릅니다.

transformation context는 transformation 객체와 연결된 private data입니다.