Wiki
TLS 지문
서버는 설치 시 자체 서명 인증서를 생성합니다. 각 클라이언트는 첫 연결 시 지문을 확인합니다.
uVersion은 기본적으로 모든 연결을 HTTPS로 암호화하며, 도메인 이름도 구매한 인증서도 필요하지 않습니다. 서버는 처음 시작할 때 인증서를 생성하고, 관리자가 그 지문을 팀에 공유하며, 각 컴퓨터가 한 번 확인합니다. 이것이 TOFU 모델입니다. 첫 접촉 시 신뢰하는 방식으로, SSH가 처음에 어떤 컴퓨터의 지문을 확인하게 하는 것과 정확히 같습니다. 그다음부터 클라이언트는 연결할 때마다 이를 대조하고, 바뀐 서버와의 통신을 거부합니다.
작업은 두 단계입니다. 서버에서 지문을 한 번 찾고, 그다음 각 컴퓨터에서 그것을 확인합니다, 컴퓨터마다 한 번씩. 이 페이지의 나머지는 참고 자료로, 무언가 바뀐 날 읽으면 됩니다.
지문 찾기
설치 마지막에 관리자 비밀번호 옆에 표시됩니다. 그다음에는 가장 간단한 것부터 가장 수동적인 것까지 세 가지 방법으로 다시 찾을 수 있습니다.
1. 브라우저에서, 아무것도 설치하지 않고
서버는 인증 없이 접근할 수 있는 정보 페이지를 제공합니다. https://서버:8443/api/server-info 를 여세요. sudo도, SSH 접속도, uVersion 계정도 필요 없어, 단연 가장 빠른 경로입니다.
브라우저는 먼저 보안 경고를 표시합니다. 이는 정상이며 예상된 일입니다. 인증서는 자체 서명되어 있어 어떤 공개 인증 기관도 이를 알지 못합니다. 사이트로 계속 진행하세요.
이어서 표시되는 페이지는 가공되지 않은 데이터 덩어리입니다. 지문은 tls_fingerprint 필드의 값으로, 콜론으로 구분된 16진수 바이트 열입니다. 팀에 전달할 것은 바로 이 문자열 전체입니다.
2. 서버 로그에서
서버는 시작할 때마다 지문을 로그에 다시 기록합니다. 이 방법은 데이터 디렉터리를 어디에 두었든 동작합니다.
# Linux (paquet .deb)
sudo journalctl -u uversion-server | grep "TLS fingerprint" | tail -1
# Docker
docker compose logs server | grep "TLS fingerprint" | tail -13. fingerprint 파일 안에서
이 파일은 인증서 옆에 기록됩니다. 즉 config.toml에 적힌 [tls] cert_path의 디렉터리입니다. 아래 경로는 기본값입니다. 데이터 디렉터리를 옮겼다면 먼저 설정에서 cert_path를 확인하세요.
# Linux, dossier de donnees par defaut
sudo cat /var/lib/uversion/data/tls/fingerprint
# Windows
Get-Content "C:\ProgramData\uVersion\data\tls\fingerprint"
# Docker : chemin fixe par l'entrypoint, sur le volume de donnees
docker compose exec server cat /data/tls/fingerprint클라이언트에서 확인하기
컴퓨터마다 한 번, 그리고 그것으로 끝입니다. 동작은 도구에 따라 다릅니다.
데스크톱 클라이언트
로그인 화면을 평소대로 입력합니다. 이 서버에 처음 연결할 때는 로그인되는 대신 Verify server identity 창이 열립니다. 표시된 지문을 관리자가 공유한 것과 대조하고, 일치하면 Trust this server를 클릭하세요. 연결은 곧바로 알아서 다시 이어집니다. 다르면 Cancel을 누르고, 이유를 물어보러 가세요.
CLI uversion
uversion trust https://uversion.example.com:8443 # interactif
uversion trust https://uversion.example.com:8443 --yes # sans question (CI, script)
uversion trusted # liste les serveurs epingles
uversion login <url> # propose l'epinglage si besoinuversion trust는 대화형입니다. 호스트, 서버 버전, TLS 모드, 지문을 표시하고, 관리자가 전달한 내용과 대조하라고 알려 준 뒤, y/N 확인을 기다립니다. 그 밖의 응답은 아무것도 고정하지 않고 취소합니다. --yes 옵션은 이 질문을 건너뜁니다. 스크립트나 지속적 통합용으로, 아무도 보지 않은 채 고정하므로, 여러분이 통제하는 신뢰할 수 있는 네트워크에서만 사용하세요.
uversion login은 서버가 아직 고정되지 않았을 때 같은 확인을 스스로 제시합니다. 컴퓨터에서는 보통 그 전에 따로 실행할 것이 없습니다.
Unreal Engine 플러그인
프로젝트를 열기 전에 터미널에서 uversion trust <url>를 한 번 실행하거나, 먼저 데스크톱 클라이언트에서 로그인하세요. 플러그인은 그 고정(핀)을 따릅니다. 에디터 내의 네이티브 대화 상자는 추후 지원 예정입니다.
Rider 플러그인
내부적으로 uversion을 사용합니다. uversion trust <url>를 한 번 실행하면 Rider가 통과합니다.
지문이 변경된 경우
클라이언트는 연결을 거부하고 이를 분명히 알립니다. 반사적으로 다시 신뢰하지 마세요. 먼저 관리자에게, 문제가 되는 연결이 아닌 다른 경로로 확인하세요. 가능한 설명은 세 가지입니다. 서버 재설치, 의도적인 인증서 교체, 또는 여러분의 컴퓨터와 서버 사이에 끼어든 누군가. 설명을 얻은 뒤에는 다음과 같이 하세요.
- 데스크톱 클라이언트: 경고 대화 상자의 Trust new fingerprint 버튼.
- CLI:
uversion mistrust <url>다음에uversion login <url>.
인증서 재생성
인증서는 기본적으로 10년간 유효하며, 갱신을 계획할 필요가 없습니다. 교체를 강제하려면(침해 의심, 감사 요건 등):
# Linux
sudo rm /var/lib/uversion/data/tls/cert.pem /var/lib/uversion/data/tls/key.pem
sudo systemctl restart uversion-server
# Windows
Remove-Item "C:\ProgramData\uVersion\data\tls\cert.pem"
Remove-Item "C:\ProgramData\uVersion\data\tls\key.pem"
Restart-Service uVersionServer서버는 시작할 때 인증서와 새 지문을 다시 생성합니다. 팀에 알리고 다시 공유하세요. 각 컴퓨터는 다시 확인해야 합니다.
자체 인증서 제공
사내 PKI나 공개 인증 기관이 발급한 여러분의 인증서를 넣을 수 있습니다. 켜야 할 옵션은 없습니다. 시작할 때 서버는 [tls] cert_path와 [tls] key_path 경로에 있는 파일을 재사용하고, 지문을 다시 계산합니다. 이는 서버가 DNS 이름을 가진 경우에만 유효합니다. 어떤 인증 기관도 사설 IP 주소에 대해 인증서를 발급하지 않습니다.
형식에 관한 세 가지 제약. 각각 이미 누군가의 저녁 시간을 통째로 잡아먹은 것들입니다.
- 인증서 파일에는 전체 체인을, 리프(말단 인증서)를 먼저 담습니다(certbot의
fullchain.pem이 바로 이 형태입니다). - 개인 키는 암호화되지 않은 PEM입니다. 암호로 보호된 키는 복호화되지 않습니다.
- 다시 시작하기 전에 두 파일을 모두 넣으세요. 하나만 찾으면 서버는 상태가 불완전하다고 보고, 남아 있던 쪽 위에 자체 서명 쌍을 다시 생성합니다.
이것이 컴퓨터에 가져오는 변화:
- 브라우저: 인증서가 담고 있는 이름으로 서버를 여는 한, 더 이상 경고가 없습니다. IP 주소로 열면 경고는 남습니다.
- 이미 고정된 컴퓨터: 지문이 바뀌므로 각 컴퓨터는 위에서 설명한 경고를 보게 되고 다시 확인해야 합니다. 교체 전에 알리세요. 그러지 않으면 팀 전체가 동시에 가로채기 메시지를 만납니다.
- 갱신: 갱신할 때마다 지문이 바뀌어 이 의식이 처음부터 다시 시작되며, 인증서는 서버가 시작할 때만 다시 읽힙니다. 90일짜리 공개 인증서라면 연간 여섯 번의 팀 전체 재확인이 됩니다. 이 비용이 해소되기 전까지는 긴 유효 기간을 택하세요.