mbedtls
Mbed TLS 3.6.2
Mbed TLS는 암호화 기본 요소, X.509 인증서 조작, SSL/TLS 및 DTLS 프로토콜을 구현하는 C 라이브러리입니다. 코드 공간이 작아 임베디드 시스템에 적합합니다.
Mbed TLS에는 PSA 암호화 API의 참조 구현이 포함되어 있습니다. 현재는 평가 목적으로만 사용되는 미리보기입니다.
Mbed TLS는 대부분의 시스템에서 기본적으로 구축되어야 합니다. 일부 플랫폼별 옵션은 완전히 문서화된 구성 파일 include/mbedtls/mbedtls_config.h 에서 사용할 수 있으며, 이 파일은 기능을 선택할 수도 있는 곳이기도 합니다. 이 파일은 수동으로 편집하거나 Python 3 스크립트 scripts/config.py 사용하여 보다 프로그래밍적인 방식으로 편집할 수 있습니다(사용 지침은 --help 사용).
Make 및 CMake 빌드 시스템을 사용할 때 CC 및 CFLAGS 와 같은 기존 환경 변수를 사용하여 컴파일러 옵션을 설정할 수 있습니다(아래 참조).
우리는 configs/ 디렉터리의 특정 사용 사례에 초점을 맞춘 몇 가지 비표준 구성을 제공합니다. configs/README.txt 에서 이에 대한 자세한 내용을 읽을 수 있습니다.
주요 Mbed TLS 문서는 ReadTheDocs를 통해 제공됩니다.
PSA 암호화 API에 대한 설명서는 GitHub에서 확인할 수 있습니다.
컴파일 타임 구성에 맞게 HTML 형식으로 라이브러리 문서의 로컬 복사본을 생성하려면 다음을 수행하십시오.
make apidoc 실행하세요.apidoc/index.html 또는 apidoc/modules.html 찾아보세요.다른 문서 소스는 SUPPORT 문서를 참조하세요.
현재 Mbed TLS 릴리스에는 세 가지 활성 빌드 시스템이 사용됩니다.
개발에 사용되는 주요 시스템은 CMake와 GNU Make입니다. 이러한 시스템은 항상 완전하고 최신 상태입니다. 다른 것들은 CMake 및 Make 빌드 시스템에 있는 모든 변경 사항을 반영해야 하지만 기능이 자동으로 이식되지 않을 수도 있습니다.
Make 및 CMake 빌드 시스템은 libmbedcrypto/libtfpsacrypto, libmbedx509 및 libmbedtls의 세 가지 라이브러리를 생성합니다. libmbedtls는 libmbedx509 및 libmbedcrypto/libtfpsacrypto에 의존하고 libmbedx509는 libmbedcrypto/libtfpsacrypto에 의존합니다. 결과적으로 일부 링커는 플래그가 특정 순서로 되어 있을 것으로 예상합니다. 예를 들어 GNU 링커는 -lmbedtls -lmbedx509 -lmbedcrypto 원합니다.
제공된 makefile을 사용하여 라이브러리를 빌드하려면 다음 도구가 필요합니다.
Mbed TLS의 development 브랜치와 mbedtls-3.6 장기 지원 브랜치는 Git 하위 모듈(프레임워크)을 사용합니다. 단순히 릴리스 태그에서 라이브러리를 컴파일하는 데는 필요하지 않습니다. 릴리스 아카이브(zip 또는 tar)를 사용하는 데는 필요하지 않습니다.
Mbed TLS의 소스 코드에는 스크립트에 의해 자동으로 생성되고 해당 콘텐츠가 플랫폼이나 라이브러리 구성이 아닌 Mbed TLS 소스에만 의존하는 일부 파일이 포함되어 있습니다. 이러한 파일은 Mbed TLS의 개발 분기에 포함되지 않지만 생성된 파일은 공식 릴리스에 포함됩니다. 이 섹션에서는 개발 브랜치에서 누락된 파일을 생성하는 방법을 설명합니다.
다음 도구가 필요합니다.
python3 -m pip install --user -r scripts/basic.requirements.txt
python3 대신 python 호출해야 할 수도 있습니다. 시스템 전체에 패키지를 설치하려면 --user 옵션을 생략하십시오. 크로스 컴파일하는 경우 구성 독립적인 파일을 생성할 때 CC 환경 변수를 호스트 플랫폼용 C 컴파일러로 설정해야 합니다.
구성 독립적인 파일을 생성하는 데 다음 방법 중 하나를 사용할 수 있습니다.
make 아무 대상이나 실행하거나 make 만 실행하면 자동으로 필요한 파일이 생성됩니다.make generated_files 실행하세요.tests/scripts/check-generated-files.sh -u 실행하여 구성과 무관한 모든 파일을 생성합니다.scriptsmake_generated_files.bat 실행하여 구성과 무관한 모든 파일을 생성합니다.GNU Make가 필요합니다. 라이브러리와 샘플 프로그램을 빌드하려면 GNU Make와 C 컴파일러이면 충분합니다. 일부 고급 빌드 타겟에는 Unix/Linux 도구가 필요합니다.
우리는 makefile을 가능한 한 간단하고 독립적으로 유지하여 사용자가 다른 플랫폼 간에 더 쉽게 이동할 수 있도록 하기 위해 의도적으로 makefile에서 최소한의 기능만 사용합니다. 더 많은 기능이 필요한 사용자는 CMake를 사용하는 것이 좋습니다.
GNU Make를 사용하여 소스 코드에서 빌드하려면 명령줄에 다음을 입력하면 됩니다.
make
테스트를 실행하려면 다음을 입력하십시오.
make check
테스트를 위해서는 Python을 구축하고 Perl을 실행해야 합니다. 그 중 하나도 설치되어 있지 않으면 다음을 사용하여 테스트 빌드를 건너뛸 수 있습니다.
make no_test
다음을 사용하면 훨씬 더 작은 테스트 세트를 계속 실행할 수 있습니다.
programs/test/selftest
Windows 플랫폼용으로 빌드하려면 대상이 Windows이지만 빌드 환경이 Unix와 유사한 경우(예: 크로스 컴파일 또는 MSYS 셸에서 컴파일하는 경우) WINDOWS=1 WINDOWS_BUILD=1 사용해야 하고, 빌드 환경은 Windows 셸입니다(예: mingw32-make 사용)(이 경우 일부 대상을 사용할 수 없음).
환경에서 SHARED 변수를 설정하면 정적 라이브러리 외에 공유 라이브러리도 빌드됩니다. DEBUG 설정하면 디버그 빌드가 제공됩니다. 환경이나 make 명령줄에서 설정하여 CFLAGS 및 LDFLAGS 재정의할 수 있습니다. 컴파일러 경고 옵션은 WARNING_CFLAGS 사용하여 별도로 재정의할 수 있습니다. 일부 디렉터리별 옵션(예: -I 지시문)은 계속 유지됩니다.
CFLAGS 설정하면 기본값인 -O2 가 무시되고 WARNING_CFLAGS 설정하면 기본값( -Wall -Wextra 로 시작)이 무시됩니다. 따라서 기본 경고 옵션에 몇 가지 경고 옵션을 추가하려는 경우 CFLAGS=-O2 -Werror 설정하면 됩니다. CFLAGS=-O2 -Werror 예를 들어. WARNING_CFLAGS 설정은 기본 내용을 제거하려는 경우에 유용합니다(예: 컴파일러가 -Wall 옵션으로 허용하지 않는 경우). 디렉터리별 옵션은 명령줄에서 재정의할 수 없습니다.
플랫폼에 따라 몇 가지 문제가 발생할 수 있습니다. 특정 플랫폼에 대해 수동으로 추가하거나 제거하는 옵션은 library/ , programs/ 및 tests/ 의 Makefile을 확인하십시오. 플랫폼이나 문제에 대한 기사를 Mbed TLS 기술 자료에서 확인할 수도 있습니다.
다른 작업도 수행해야 하는 경우 Mbed TLS 기술 자료에 추가할 수 있도록 알려 주시기 바랍니다.
별도의 디렉터리에서 CMake를 사용하여 소스를 빌드하려면(권장) 명령줄에 다음을 입력하면 됩니다.
mkdir /path/to/build_dir && cd /path/to/build_dir
cmake /path/to/mbedtls_source
cmake --build .
테스트를 실행하려면 다음을 입력하십시오.
ctest
테스트 스위트를 구축하려면 Python이 필요하고 Perl을 실행해야 합니다. 이들 중 하나가 설치되어 있지 않으면 다음을 사용하여 테스트 스위트를 비활성화할 수 있습니다.
cmake -DENABLE_TESTING=Off /path/to/mbedtls_source
테스트 스위트를 비활성화했지만 프로그램은 활성화된 상태로 유지한 경우에도 다음을 사용하여 훨씬 더 작은 테스트 세트를 실행할 수 있습니다.
programs/test/selftest
공유 라이브러리 구축을 위해 CMake를 구성하려면 다음을 사용하세요.
cmake -DUSE_SHARED_MBEDTLS_LIBRARY=On /path/to/mbedtls_source
CMake 빌드 시스템 내에서는 다양한 빌드 모드를 사용할 수 있습니다. 대부분은 gcc 및 clang에 사용할 수 있지만 일부는 컴파일러에 따라 다릅니다.
Release . 이는 바이너리 파일에 불필요한 정보 없이 기본 코드를 생성합니다.Debug . 이는 디버그 정보를 생성하고 코드 최적화를 비활성화합니다.Coverage . 이는 디버그 정보 외에 코드 적용 범위 정보를 생성합니다.ASan . 이는 메모리 오류를 확인하기 위해 AddressSanitizer로 코드를 계측합니다. (여기에는 최신 버전의 gcc 및 clang이 있는 LeakSanitizer가 포함됩니다.) (최신 버전의 clang을 사용하면 이 모드는 정의되지 않은 동작을 확인하기 위해 UndefineSanitizer를 사용하여 코드를 계측합니다.)ASanDbg . ASan과 동일하지만 디버그 정보와 더 나은 스택 추적이 포함되어 더 느립니다.MemSan . 초기화되지 않은 메모리 읽기를 확인하기 위해 MemorySanitizer로 코드를 계측합니다. 실험적이며 Linux/x86_64에서 최신 clang이 필요합니다.MemSanDbg . MemSan과 동일하지만 디버그 정보, 더 나은 스택 추적 및 원본 추적 기능이 있어 속도가 느립니다.Check . 이는 최적화에 의존하는 컴파일러 경고를 활성화하고 모든 경고를 오류로 처리합니다.CMake에서 빌드 모드를 전환하는 것은 간단합니다. 디버그 모드의 경우 명령줄에 다음을 입력합니다.
cmake -D CMAKE_BUILD_TYPE=Debug /path/to/mbedtls_source
사용 가능한 다른 CMake 옵션을 나열하려면 다음을 사용하세요.
cmake -LH
CMake를 사용하면 cmake를 처음 호출한 후에는 컴파일러나 해당 플래그를 조정할 수 없습니다. 이는 CC=your_cc make 및 make CC=your_cc 작동 하지 않음 을 의미합니다( CFLAGS 및 기타 변수와 유사하게). cmake를 처음 호출할 때 이러한 변수를 조정해야 합니다. 예를 들면 다음과 같습니다.
CC=your_cc cmake /path/to/mbedtls_source
이미 cmake를 호출했고 해당 설정을 변경하려면 빌드 디렉터리를 제거하고 다시 만들어야 합니다.
내부 구축이 가능하다는 점에 유의하세요. 그러나 이는 제공된 Makefile을 덮어쓰게 됩니다( git status 수정된 것으로 표시되지 않도록 하려면 scripts/tmp_ignore_makefiles.sh 참조). 이렇게 하려면 Mbed TLS 소스 디렉터리에서 다음을 사용하세요.
cmake .
make
나중에 CC 또는 CFLAGS 변경하려면 CMake 캐시를 제거해야 합니다. 이는 GNU find를 사용하여 다음 명령으로 수행할 수 있습니다.
find . -iname '*cmake*' -not -name CMakeLists.txt -exec rm -rf {} +
이제 원하는 대로 변경할 수 있습니다.
CC=your_cc cmake .
make
변수와 관련하여 cmake를 호출할 때 CFLAGS를 설정하면 CFLAGS 값은 cmake에서 제공하는 콘텐츠(위에 표시된 빌드 모드에 따라 다름)를 재정의하지 않고 단지 그 앞에 추가될 뿐입니다.
Mbed TLS는 다른 CMake 프로젝트에서 종속성으로 사용할 패키지 구성 파일을 제공합니다. 다음을 사용하여 Mbed TLS의 CMake 대상을 직접 포함할 수 있습니다.
find_package(MbedTLS)
메시지가 표시되면 MbedTLS_DIR ${YOUR_MBEDTLS_INSTALL_DIR}/cmake 로 설정합니다. 그러면 다음과 같은 대상이 생성됩니다.
MbedTLS::tfpsacrypto (암호화 라이브러리)MbedTLS::mbedtls (TLS 라이브러리)MbedTLS::mbedx509 (X509 라이브러리) 그런 다음 target_link_libraries() 통해 직접 사용할 수 있습니다.
add_executable(xyz)
target_link_libraries(xyz
PUBLIC MbedTLS::mbedtls
MbedTLS::tfpsacrypto
MbedTLS::mbedx509)
그러면 Mbed TLS 라이브러리가 라이브러리 또는 애플리케이션에 연결되고 해당 포함 디렉터리가 대상에 추가됩니다( PUBLIC 또는 INTERFACE 링크 라이브러리의 경우 전이적으로).
Mbed TLS는 CMake 하위 프로젝트로 빌드되는 것을 지원합니다. 상위 CMake 프로젝트의 add_subdirectory() 사용하여 Mbed TLS를 하위 프로젝트로 포함할 수 있습니다.
Microsoft Visual Studio용 빌드 파일은 Visual Studio 2017용으로 생성됩니다.
솔루션 파일 mbedTLS.sln 에는 라이브러리와 모든 프로그램을 빌드하는 데 필요한 모든 기본 프로젝트가 포함되어 있습니다. 테스트 파일은 Python 및 Perl 환경도 필요하므로 생성 및 컴파일되지 않습니다. 그러나 programs/test/ 의 자체 테스트 프로그램은 계속 사용할 수 있습니다.
Mbed TLS의 개발 분기에서는 "개발 분기에서 생성된 소스 파일"에 설명된 대로 Visual Studio 솔루션 파일을 먼저 생성해야 합니다.
우리는 다양한 기능과 용도에 대한 예제 프로그램을 programs/ 에 포함시켰습니다. 이러한 샘플 프로그램의 목적은 라이브러리의 특정 기능을 보여주는 것이며 실제 응용 프로그램을 구축하려면 코드를 조정해야 할 수도 있습니다.
Mbed TLS에는 테스트 파일(예: test_suite_ssl.c )을 생성하기 위해 처음에 Python이 필요한 tests/ 에 정교한 테스트 모음이 포함되어 있습니다. 이러한 파일은 function file (예: suites/test_suite_ssl.function ) 및 data file (예: suites/test_suite_ssl.data )에서 생성됩니다. function file 테스트 함수가 포함되어 있습니다. data file 에는 테스트 함수에 전달될 매개변수로 지정된 테스트 사례가 포함되어 있습니다.
Unix 셸과 OpenSSL(및 선택적으로 GnuTLS)이 설치된 시스템의 경우 추가 테스트 스크립트를 사용할 수 있습니다.
tests/ssl-opt.sh 다양한 TLS 옵션(재협상, 재개 등)에 대한 통합 테스트를 실행하고 이러한 옵션과 다른 구현의 상호 운용성을 테스트합니다.tests/compat.sh 모든 암호 모음과 다른 구현의 상호 운용성을 테스트합니다.tests/scripts/test-ref-configs.pl 테스트는 다양한 축소 구성으로 빌드됩니다.tests/scripts/depends.py 테스트는 단일 곡선, 키 교환, 해시, 암호 또는 pkalg를 사용하는 구성으로 빌드됩니다.tests/scripts/all.sh 다양한 빌드 옵션(예: ASan, 전체 mbedtls_config.h 등)을 사용하여 위 테스트와 추가 테스트의 조합을 실행합니다.테스트에 필요한 모든 도구의 필수 버전을 수동으로 설치하는 대신 테스트 인프라 저장소에 설명된 대로 CI 시스템의 Docker 이미지를 사용할 수 있습니다.
Mbed TLS는 다양한 아키텍처, OS 및 플랫폼으로 이식될 수 있습니다. 포트를 시작하기 전에 다음 기술 자료 문서가 유용할 수 있습니다.
Mbed TLS는 대부분 휴대용 C99로 작성되었습니다. 그러나 표준을 뛰어넘지만 대부분의 최신 아키텍처에서 충족되는 몇 가지 플랫폼 요구 사항이 있습니다.
int 및 size_t 너비가 32비트 이상이어야 합니다.uint8_t , uint16_t , uint32_t 유형 및 서명된 해당 항목을 사용할 수 있어야 합니다.Arm의 PSA(플랫폼 보안 아키텍처)는 위협 모델, 보안 분석, 하드웨어 및 펌웨어 아키텍처 사양, 오픈 소스 펌웨어 참조 구현의 전체적인 집합입니다. PSA는 업계 모범 사례를 기반으로 하드웨어 및 펌웨어 수준 모두에서 보안을 일관되게 설계할 수 있는 방법을 제공합니다.
PSA 암호화 API는 일련의 암호화 기본 요소에 대한 액세스를 제공합니다. 그것은 두 가지 목적을 가지고 있습니다. 첫째, PSA 호환 플랫폼에서 보안 부팅, 보안 스토리지, 보안 통신과 같은 서비스를 구축하는 데 사용할 수 있습니다. 둘째, 모든 플랫폼에서 다른 PSA 구성 요소와 독립적으로 사용할 수도 있습니다.
PSA 암호화 API의 설계 목표는 다음과 같습니다.
Arm은 API 설계에 대한 피드백을 환영합니다. 개선할 점이 있다고 생각되면 Github 저장소에서 문제를 열어주세요. 또는 개인적으로 피드백을 제공하고 싶다면 [email protected] 으로 이메일을 보내주세요. 이메일로 받은 모든 피드백은 기밀로 처리됩니다.
Mbed TLS에는 PSA 암호화 API의 참조 구현이 포함되어 있습니다. 그러나 전체 사양을 구현하는 것을 목표로 하는 것은 아닙니다. 특히 모든 알고리즘을 구현하지는 않습니다.
X.509 및 TLS 코드는 대부분의 작업에 PSA 암호화를 사용할 수 있습니다. 이 지원을 활성화하려면 mbedtls_config.h 에서 컴파일 옵션 MBEDTLS_USE_PSA_CRYPTO 활성화하세요. TLS 1.3은 이 옵션에 관계없이 대부분의 작업에 PSA 암호화를 사용합니다. 자세한 내용은 docs/use-psa-crypto.md 참조하세요.
Mbed TLS는 암호화 가속기, 보안 요소 및 무작위 생성기용 드라이버를 지원합니다. 이 작업이 진행 중입니다. 드라이버 인터페이스는 아직 완전히 안정적이지 않으며 예고 없이 변경될 수 있습니다. 우리는 PSA Crypto API를 사용하여 애플리케이션 코드에 대한 이전 버전과의 호환성을 유지하려고 하지만 드라이버 코드는 Mbed TLS의 향후 마이너 릴리스에서 변경되어야 할 수도 있습니다.
드라이버 작성에 대한 자세한 내용은 PSA 드라이버 예제 및 가이드를 참조하세요.
드라이버를 사용할 때 일반적으로 두 가지 컴파일 옵션을 활성화하는 것이 좋습니다(자세한 내용은 참조 설명서 참조).
MBEDTLS_USE_PSA_CRYPTO 가 필요합니다.MBEDTLS_PSA_CRYPTO_CONFIG 사용하면 해당 소프트웨어 구현 코드를 포함하지 않고 PSA 암호화 메커니즘을 활성화할 수 있습니다. 이는 아직 모든 메커니즘에서 지원되지 않습니다. 파일에 별도로 명시하지 않는 한 Mbed TLS 파일은 이중 Apache-2.0 또는 GPL-2.0 이상 라이센스에 따라 제공됩니다. 이러한 라이센스의 전체 텍스트는 LICENSE 파일을 참조하고, 자세한 내용은 기여 지침의 '라이센스 및 저작권' 섹션을 참조하세요.
이 프로젝트에는 다른 프로젝트의 코드가 포함되어 있습니다. 이 코드는 tf-psa-crypto/drivers/ 디렉터리에 있습니다. 원본 라이센스 텍스트는 일반 Mbed TLS 라이센스 및/또는 소스 파일과 다른 프로젝트 하위 디렉터리에 포함됩니다. 프로젝트는 다음과 같습니다.
drivers/everest/ : 파일은 Project Everest에서 유래되었으며 Apache 2.0 라이센스에 따라 배포됩니다.drivers/p256-m/p256-m/ : p256-m 저장소에서 파일을 가져왔습니다. 원본 저장소의 코드는 Apache 2.0 라이센스에 따라 배포됩니다. 작성자의 허가를 받아 이중 Apache-2.0 또는 GPL-2.0 이상 라이센스에 따라 Mbed TLS로 배포됩니다. 우리는 커뮤니티의 버그 보고서와 기여를 감사하게 받아들입니다. 이를 수행하는 방법에 대한 자세한 내용은 기여 지침을 참조하세요.
SECURITY.md 참조하세요.SUPPORT.md 참조하세요.
