부가 기능 버저닝(Versioning)
부가 기능은 Toolkit version format을 이용해 자신의 버전을 명시해야 합니다. 이는 다음과 같이 점으로 분리된 버전 문자열이라고 말씀드릴 수 있습니다.
- 2.0
- 1.0b1
- 3.0pre1
- 5.0.1.2
응용 프로그램의 호환성 검사 방법
부가기능을 설치하기 전에 응용 프로그램은 부가기능의 <tt>install.rdf</tt>에 있는 targetApplication 항목을 조사합니다. 해당 항목에는 대상 응용프로그램과 동일한 ID가 존재해야 합니다. 또한 이 항목의 minVersion과 maxVersion은 부가기능이 실행되는 응용프로그램의 버전이 포함되는 범위이어야 합니다.
만일 응용프로그램이 targetApplication 요소를 가지고 있지만 호환되지 않는 버전일 경우 부가 기능의 updateURL에서 업데이트된 호환 정보를 조회해 제공합니다.
만일 <tt>install.rdf</tt>에 targetPlatform 항목들이 포함되어 있으며, 현재 응용프로그램이 실행되는 플랫폼이 해당 목록에 포함되어 있지 않을 경우 설치가 거부됩니다.
Gecko 1.9 기반의 응용프로그램일 경우 targetApplication 항목에 응용프로그램이 실행되는 툴킷 버전에 해당하는 [email protected], minVersion, maxVersion 값을 사용할 수 있습니다. 이는 여러분의 부가 기능이 해당 툴킷 기반의 어떤 응용프로그램에서도 설치 가능하다는 것을 나타냅니다.
호환성 검사 무시하기
테스트를 목적으로 할 경우 응용프로그램에 부가기능을 설치할 때 호환성 검사를 무시하도록 할 수 있습니다. 연산자(boolean) 형으로 extensions.checkCompatibility 설정을 만들고 false로 지정하면 됩니다.
app.extensions.version 설정을 통해 응용프로그램의 버전을 오버라이드할 수도 있습니다. 이는 응용프로그램 자신이 호환되지 않는 확장 기능을 설치할 수 있다고 믿게끔 해 줍니다.minVersion과 maxVersion 결정하기
minVersion과 maxVersion은 여러분이 테스트한 응용프로그램의 버전 범위로 명시하는게 좋습니다. 특히 향후 API와 UI가 어떻게 변경될지 모르기 때문에 maxVersion을 현재 가능한 응용프로그램의 버전보다 높게 설정하지 않아야 합니다. 호환성 업데이트를 이용하면 확장기능의 새로운 버전을 공개할 필요 없이 maxVersion만 증가시키면 됩니다.
maxVersion에서는 여러분이 지원하는 응용프로그램의 하위(minor) 버전 위치에 *를 사용할 수 있습니다. 예를 들어 2.0.0.*은 2 버전 응용프로그램에서의 하위 업데이트를 지원하는다는 것을 의미합니다. 응용 프로그램은 보통 확장 기능 작성자에게 버전의 어떤 부분을 이렇게 사용할 수 있는지 제안할 것입니다.
실수로 *를 어떤 버전도 지원한다는 의미로 생각하지 마세요. 사실 *는 무한의 높은 숫자를 나타내며, 따라서 maxVersion에서 사용하였을때만 의미가 있습니다. 이를 minVersion에서 사용하면 여러분이 원하는 효과가 나지 않을 수 있습니다.
자동 부가기능 업데이트 검사
응용프로그램은 주기적으로 설치된 부가기능의 updateURL에서 정보를 가져와 업데이트 여부를 검사합니다. 반환된 정보는 사용자에게 부가기능의 업데이트된 버전이 있는지를 알려주고 응용프로그램에게는 해당 부가기능과 호환되는 응용프로그램의 버전을 알려줍니다.
호환성 업데이트
자동 업데이트 검사를 통해 응용프로그램은 현재 설치된 부가 기능 버전에 대한 새로운 버전과 갱신된 호환성 정보를 조사합니다. 만일 작성된 업데이트 선언에 현재 설치된 부가 기능에 대한 항목이 존재하고 해당 항목의 targetApplication에 더 큰 maxVersion이 명시되어 있을 경우, 응용 프로그램은 부가 기능의 <tt>install.rdf</tt>에 명시된 값 대신 이 값을 사용하게 됩니다. 이는 호환성 문제로 사용 안함 상태로 되어 있는 부가 기능을 사용 가능한 상태로 만들 수도 있으며, 정상적으로 설치되지 않은 부가 기능을 정상적으로 설치된 상태로 만들 수도 있습니다.
업데이트 RDF 포맷
여러분이 부가기능의 updateURL을 직접 호스팅하는 경우, 부가기능의 버전 정보를 RDF 포맷으로 반환해야만 합니다. 아래는 업데이트 선언(update manifest) 예제입니다. 여기서는 id가 [email protected]인 서로 다른 2가지 버전의 확장기능에 대한 정보를 나열하고 있습니다. 포함된 버전은 2.2와 2.5 이고 둘 다 Firefox 1.5에서 2.0.0.* 버전에서 호환된다고 명시하고 있습니다. 버전 2.2의 경우 https 업데이트 링크를 사용하고 있으며, 버전 2.5는 일반적인 http 링크를 사용하며 전송된 파일의 유효성을 검사하기 위해 해시를 포함하고 있습니다.
맨 처음에 있는 RDF:Description의 about 속성을 올바르게 설정하는 것이 중요합니다. 이 속성은 제공 정보가 어떤 종류의 부가기능에 대한 것인지에 따라 다음과 같이 달라집니다.
- 확장 기능일 경우
urn:mozilla:extension:<id>이어야 합니다. - 테마인 경우
urn:mozilla:theme:<id>이어야 합니다. - 이 외의 다른 유형인 경우
urn:mozilla:item:<id>이어야 합니다.
아래 예제의 경우 이후 버전이 이전 버전보다 나중에 명시되어야 한다는 점에서 <RDF:Seq> 요소 내에 있는 버전의 순서가 중요합니다. 만일 최종 버전이 제공된다면 이전 버전 모두가 명시될 필요는 없습니다(?).
<?xml version="1.0" encoding="UTF-8"?>
<RDF:RDF xmlns:RDF="https://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:em="https://www.mozilla.org/2004/em-rdf#">
<!-- Description 리소스에는 id가 [email protected]인
단일 부가 기능에 대한 모든 업데이트와 호환성 정보를 포함합니다.
여러분은 하나의 RDF 파일에 여러개의 부가기능에 대한 정보를 나열할 수 있습니다. -->
<RDF:Description about="urn:mozilla:extension:[email protected]">
<em:updates>
<RDF:Seq>
<!-- 각각의 li는 동일한 부가기능에 대한 서로 다른 버전을 나타냅니다. -->
<RDF:li>
<RDF:Description>
<em:version>2.2</em:version> <!-- 이것은 부가기능의 버전 번호입니다. -->
<!-- 이 부가 기능과 호환되는 각각의 응용 프로그램에 대해 targetApplication이 하나씩 존재합니다. -->
<em:targetApplication>
<RDF:Description>
<em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
<em:minVersion>1.5</em:minVersion>
<em:maxVersion>2.0.0.*</em:maxVersion>
<!-- 이 부가 기능을 다운로드 받을 위치를 나타냅니다. -->
<em:updateLink>https://www.mysite.com/foobar2.2.xpi</em:updateLink>
<!-- 업데이트된 버전에서 제공되는 새로운 기능을 설명하는 페이지에 대한 URL입니다. -->
<em:updateInfoURL>https://www.mysite.com/updateinfo2.2.xhtml</em:updateInfoURL>
</RDF:Description>
</em:targetApplication>
</RDF:Description>
</RDF:li>
<RDF:li>
<RDF:Description>
<em:version>2.5</em:version>
<em:targetApplication>
<RDF:Description>
<em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
<em:minVersion>1.5</em:minVersion>
<em:maxVersion>2.0.0.*</em:maxVersion>
<em:updateLink>https://www.mysite.com/foobar2.5.xpi</em:updateLink>
<em:updateHash>sha1:78fc1d2887eda35b4ad2e3a0b60120ca271ce6e6</em:updateHash>
</RDF:Description>
</em:targetApplication>
</RDF:Description>
</RDF:li>
</RDF:Seq>
</em:updates>
<!-- 서명은 부가기능의 install.rdf에 updateKey를 포함하고 있는 경우에만 필요합니다. -->
<em:signature>MIGTMA0GCSqGSIb3DQEBBQUAA4GBAMO1O2gwSCCth1GwYMgscfaNakpN40PJfOWt
ub2HVdg8+OXMciF8d/9eVWm8eH/IxuxyZlmRZTs3O5tv9eWAY5uBCtqDf1WgTsGk
jrgZow1fITkZI7w0//C8eKdMLAtGueGfNs2IlTd5P/0KH/hf1rPc1wUqEqKCd4+L
BcVq13ad</em:signature>
</RDF:Description>
</RDF:RDF>
어떤 사람들은 다음의 포맷을 더 좋아합니다(본 예제에서는 기본 구조를 중점적으로 보여주기 위해 몇 가지 정보가 생략되어 있습니다).
<?xml version="1.0" encoding="UTF-8"?>
<RDF:RDF xmlns:RDF="https://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:em="https://www.mozilla.org/2004/em-rdf#">
<!-- Description 리소스에는 id가 [email protected]인
단일 부가 기능에 대한 모든 업데이트와 호환성 정보를 포함합니다.
여러분은 하나의 RDF 파일에 여러개의 부가기능에 대한 정보를 나열할 수 있습니다. -->
<RDF:Description about="urn:mozilla:extension:[email protected]">
<em:updates>
<RDF:Seq>
<!-- resource 속성은 아래에 있는 RDF:Description의 동일한 about 속성을 가리킵니다.
실제 uri는 어떤 값이든 상관 없습니다. -->
<RDF:li resource="urn:mozilla:extension:[email protected]:2.2"/>
<RDF:li resource="urn:mozilla:extension:[email protected]:2.5"/>
</RDF:Seq>
</em:updates>
<em:signature>MIGTMA0GCSqGSIb3DQEBBQUAA4GBAMO1O2gwSCCth1GwYMgscfaNakpN40PJfOWt
ub2HVdg8+OXMciF8d/9eVWm8eH/IxuxyZlmRZTs3O5tv9eWAY5uBCtqDf1WgTsGk
jrgZow1fITkZI7w0//C8eKdMLAtGueGfNs2IlTd5P/0KH/hf1rPc1wUqEqKCd4+L
BcVq13ad</em:signature>
</RDF:Description>
<!-- 다음은 앞선 예제에서 li 요소 내에 있는 Description과 동일합니다. -->
<RDF:Description about="urn:mozilla:extension:[email protected]:2.2">
<em:version>2.2</em:version>
<!-- 나머지 내용은 생략하였습니다. -->
</RDF:Description>
<RDF:Description about="urn:mozilla:extension:[email protected]:2.5">
<em:version>2.5</em:version>
<!-- 나머지 내용은 생략하였습니다. -->
</RDF:Description>
</RDF:RDF>
갱신 사항에 대한 세부 정보 제공하기
부가 기능 사용자에게 갱신된 사항에 대한 세부 정보를 제공할 수 있습니다. 이는 사용자가 부가 기능의 업데이트 알림을 받은 경우에만 보여지는 것으로, 어떤 기능이 새롭게 추가되었고 보안과 관련된 어떤 문제들이 해결되었는지 등에 대한 빠른 개요를 제공해주는데 사용될 수 있습니다.
이를 위해 먼저 업데이트 선언 파일에 updateInfoURL 항목을 추가해야 합니다(위 예제를 보세요). 이 URL에 해당하는 페이지가 사용자에게 출력됩니다. 이 페이지는 일반적인 웹 페이지 외부에 출력되므로 깨끗하게 만들어져야 합니다. 이는 몇 가지 사항만이 가능하고 스크립트나 이미지들은 사용할 수 없다는 것을 의미합니다. 일반 규칙으로 다음의 태그들만 사용하는게 좋으며, 다른 태그들은 무시됩니다.
- 제목으로 사용되는 h1, h2, h3
- 문단으로 사용되는 p
- 목록으로 사용되는 ul과 ol
목록 내에서는 개별 항목을 나타내는 li 태그를 사용합니다.
h1, h2, h3, p, li 태그 내에서는 다음을 사용할 수 있습니다.
- 두꺼운 글자를 위해 b 나 strong
- 이탤릭 글자를 위해 i 나 em
해당 페이지는 완전히 유효한 XHTML이어야 하면 MIME type이 application/xhtml+xml어야 합니다.
업데이트 선언 파일의 updateInfoURL에는 URL에 로케일 정보를 포함하고자 할 경우 %APP_LOCALE%을 포함할 수 있습니다. 이를 이용하면 사용자의 로케일에 따라 내용을 수정할 수 있습니다. 이 외에도 updateURL에서 지원하는 또 다른 치환 문자열을 사용할 수 있습니다만, 별로 필요하지는 않을 것입니다.
보안 업데이트
Gecko 1.9는 부가 기능 업데이트와 같은 경우에 사용자를 man-in-the-middle attacks에서 보호하기 위해 설계된 부가적인 요구 사항을 추가했습니다. 이미 설치된 부가 기능의 install.rdf에서 updateURL을 다음 방법 중 한 가지로 지정해야 합니다.
updateURL이 https를 사용하거나updateURL이 전혀 없습니다 (which defaults to <tt>addons.mozilla.org</tt> which is https).updateURL이 http를 사용하고 업데이트 선언에 있는 데이터를 확인하는데 사용할updateKey항목을 지정합니다.
<tt>install.rdf</tt>에서 updateKey를 지정할 때는 업데이트 선언에 digital signature를 포함해야 하며 그렇지 않으면 정보가 거부됩니다.
updateURL에서 전달된 업데이트 선언에서는 updateLink를 다음 방법 중 한 가지로 지정해야 합니다.
- XPI 파일을 가리키는
updateLink는 꼭 https를 사용해야 합니다. updateLink가 http를 사용할 수 있으며, sha1, sha256, sha384, sha512 중 하나의 알고리즘을 이용하여 XPI 파일에 대한updateHash를 포함해야 합니다.
업데이트 선언에서 위의 두 가지 요구 사항 중 하나를 만족하지 못하는 모든 항목은 새로운 버전을 확인할 때 무시됩니다.
잘못된 인증서를 가진 사이트로 가는 https 링크나 http 사이트로 리디렉트하는 것은 <tt>update.rdf</tt>와 updateLink의 두 가지 경우에 모두 실패합니다.
업데이트 해시
다운로드한 XPI의 무결성을 확인하기 위하여 updateLink와 함께 updateHash 항목을 제공해야 합니다. 이 해시는 파일 데이터에 대하여 문자열 형식으로 생성해야 합니다. 문자열의 시작에 사용한 해시 알고리즘을 넣고 :으로 해시와 구별합니다.
<em:updateHash>sha1:78fc1d2887eda35b4ad2e3a0b60120ca271ce6e6</em:updateHash>
해시가 지정되면 다운로드한 파일을 해시와 비교하고 일치하지 않으면 오류를 표시합니다.
업데이트 선언 서명하기
업데이트 RDF를 일반 http로 제공하기를 원한다면, Gecko 1.9 기반의 애플리케이션에서는 업데이트 선언을 서명해야 합니다. 이는 해당 정보를 생성한 여러분과 그것을 추출하는 애플리케이션 사이에서 간섭이 없었다는 것을 확인하기 위한 것입니다. 업데이트 RDF를 서명하는 데에는 McCoy 도구를 사용해야 합니다.
서명 방식에 대한 기술적인 세부 사항은 이 문서의 범위를 벗어나지만 기본적인 사항은 다음과 같습니다.
부가 기능 작성자가 공개/개인 RSA 암호 키 쌍을 생성합니다.
공개키는 DER로 인코드된 후에 base 64로 인코드되어 부가 기능의 <tt>install.rdf</tt>에 updateKey 항목으로 추가됩니다.
작성자가 업데이트 RDF 파일을 생성할 때 도구를 사용하여 개인키로 서명합니다. 대략적으로 이야기하면, 업데이트 정보는 문자열로 변환되어 sha512 해시 알고리즘으로 해시되고 개인키로 이 해시를 서명합니다. 결과 데이터는 DER로 인코드하고 base 64로 인코드한 후 업데이트 RDF에 em:signature 항목으로 포함합니다.