home *** CD-ROM | disk | FTP | other *** search
/ Chip 1998 February / CHIP_2_98.iso / misc / src / rpm / docs / format < prev    next >
Text File  |  1997-09-17  |  10KB  |  247 lines
  1. RPM File Format
  2. ===============
  3.  
  4. This document describes the RPM file format version 3.0, which is used
  5. by RPM versions 2.1 and greater.  The format is subject to change, and
  6. you should not assume that this document is kept up to date with the
  7. latest RPM code.  That said, the 3.0 format should not change for
  8. quite a while, and when it does, it will not be 3.0 anymore :-).  In
  9. any case, THE PROPER WAY TO ACCESS THESE STRUCTURES IS THROUGH THE RPM
  10. LIBRARY!!
  11.  
  12. The RPM file format covers both source and binary packages.  An RPM
  13. package file is divided in 4 logical sections:
  14.  
  15. . Lead      -- 96 bytes of "magic" and other info
  16. . Signature -- collection of "digital signatures"
  17. . Header    -- holding area for all the package information
  18. . Archive   -- compressed archive of all the files in the package
  19.  
  20. All 2 and 4 byte "integer" quantities (int16 and int32) are stored in
  21. network byte order.  When data is presented, the first number is the
  22. byte number, or address, in hex, followed by the byte values in hex,
  23. followed by character "translations" (where appropriate).
  24.  
  25. Lead
  26. ----
  27.  
  28. The Lead is basically for file(1).  All the information contained in
  29. the Lead is duplicated or superceded by information in the Header.
  30. Much of the info in the Lead was used in old versions of RPM but is
  31. now ignored.  The Lead is stored as a C structure:
  32.  
  33. struct rpmlead {
  34.     unsigned char magic[4];
  35.     unsigned char major, minor;
  36.     short type;
  37.     short archnum;
  38.     char name[66];
  39.     short osnum;
  40.     short signature_type;
  41.     char reserved[16];
  42. };
  43.  
  44. and is illustrated with one pulled from the rpm-2.1.2-1.i386.rpm
  45. package:
  46.  
  47. 00000000: ed ab ee db 03 00 00 00
  48.  
  49. The first 4 bytes (0-3) are "magic" used to uniquely identify an RPM
  50. package.  It is used by RPM and file(1).  The next two bytes (4, 5)
  51. are int8 quantities denoting the "major" and "minor" RPM file format
  52. version.  This package is in 3.0 format.  The following 2 bytes (6-7)
  53. form an int16 which indicates the package type.  As of this writing
  54. there are only two types: 0 == binary, 1 == source.
  55.  
  56. 00000008: 00 01 72 70 6d 2d 32 2e    ..rpm-2.
  57.  
  58. The next two bytes (8-9) form an int16 that indicates the architecture
  59. the package was built for.  While this is used by file(1), the true
  60. architecture is stored as a string in the Header.  See, lib/misc.c for
  61. a list of architecture->int16 translations.  In this case, 1 == i386.
  62. Starting with byte 10 and extending to byte 75, are 65 characters and
  63. a null byte which contain the familiar "name-version-release" of the
  64. package, padded with null (0) bytes.
  65.  
  66. 00000010: 31 2e 32 2d 31 00 00 00    1.2-1...
  67. 00000018: 00 00 00 00 00 00 00 00    ........
  68. 00000020: 00 00 00 00 00 00 00 00    ........
  69. 00000028: 00 00 00 00 00 00 00 00    ........
  70. 00000030: 00 00 00 00 00 00 00 00    ........
  71. 00000038: 00 00 00 00 00 00 00 00    ........
  72. 00000040: 00 00 00 00 00 00 00 00    ........
  73. 00000048: 00 00 00 00 00 01 00 05    ........
  74.  
  75. Bytes 76-77 ("00 01" above) form an int16 that indicates the OS the
  76. package was built for.  In this case, 1 == Linux.  The next 2 bytes
  77. (78-79) form an int16 that indicates the signature type.  This tells
  78. RPM what to expect in the Signature.  For version 3.0 packages, this
  79. is 5, which indicates the new "Header-style" signatures.
  80.  
  81. 00000050: 04 00 00 00 68 e6 ff bf    ........
  82. 00000058: ab ad 00 08 3c eb ff bf    ........
  83.  
  84. The remaining 16 bytes (80-95) are currently unused and are reserved
  85. for future expansion.
  86.  
  87. Signature
  88. ---------
  89.  
  90. A 3.0 format signature (denoted by signature type 5 in the Lead), uses
  91. the same structure as the Header.  For historical reasons, this
  92. structure is called a "header structure", which can be confusing since
  93. it is used for both the Header and the Signature.  The details of the
  94. header structure are given below, and you'll want to read them so the
  95. rest of this makes sense.  The tags for the Signature are defined in
  96. lib/signature.h.
  97.  
  98. The Signature can contain multiple signatures, of different types.
  99. There are currently only three types, each with its own tag in the
  100. header structure:
  101.  
  102.     Name    Tag    Header Type
  103.     ----    ----    -----------
  104.     SIZE    1000    INT_32
  105.     MD5    1001    BIN
  106.     PGP    1002    BIN
  107.  
  108. The MD5 signature is 16 bytes, and the PGP signature varies with
  109. the size of the PGP key used to sign the package.
  110.  
  111. As of RPM 2.1, all packages carry at least SIZE and MD5 signatures,
  112. and the Signature section is padded to a multiple of 8 bytes.
  113.  
  114. Header
  115. ------
  116.  
  117. The Header contains all the information about a package: name,
  118. version, file list, etc.  It uses the same "header structure" as the
  119. Signature, which is described in detail below.  A complete list of the
  120. tags for the Header would take too much space to list here, and the
  121. list grows fairly frequently.  For the complete list see lib/rpmlib.h
  122. in the RPM sources.
  123.  
  124. Archive
  125. -------
  126.  
  127. The Archive is currently a gzipped cpio archive.  The cpio
  128. archive type used is SVR4 with a CRC checksum.
  129.  
  130. The Header Structure
  131. --------------------
  132.  
  133. The header structure is a little complicated, but actually performs a
  134. very simple function.  It acts almost like a small database in that it
  135. allows you to store and retrieve arbitrary data with a key called a
  136. "tag".  When a header structure is written to disk, the data is
  137. written in network byte order, and when it is read from disk, is is
  138. converted to host byte order.
  139.  
  140. Along with the tag and the data, a data "type" is stored, which indicates,
  141. obviously, the type of the data associated with the tag.  There are
  142. currently 9 types:
  143.  
  144.     Type        Number
  145.     ----        ------
  146.     NULL        0
  147.     CHAR        1
  148.     INT8        2
  149.     INT16        3
  150.     INT32        4
  151.     INT64        5
  152.     STRING        6
  153.     BIN        7
  154.     STRING_ARRAY    8
  155.  
  156. One final piece of information is a "count" which is stored with each
  157. tag, and indicates the number of items of the associated type that are
  158. stored.  As a special case, the STRING type is not allowed to have a
  159. count greater than 1.  To store more than one string you must use a
  160. STRING_ARRAY.
  161.  
  162. Altogether, the tag, type, count, and data are called an "Entry" or
  163. "Header Entry".
  164.  
  165. 00000000: 8e ad e8 01 00 00 00 00    ........
  166.  
  167. A header begins with 3 bytes of magic "8e ad e8" and a single byte to
  168. indicate the header version.  The next four bytes (4-7) are reserved.
  169.  
  170. 00000008: 00 00 00 20 00 00 07 77    ........
  171.  
  172. The next four bytes (8-11) form an int32 that is a count of the number
  173. of entries stored (in this case, 32).  Bytes 12-15 form an int32 that
  174. is a count of the number of bytes of data stored (that is, the number
  175. of bytes made up by the data portion of each entry).  In this case it
  176. is 1911 bytes.
  177.  
  178. 00000010: 00 00 03 e8 00 00 00 06 00 00 00 00 00 00 00 01    ................
  179.  
  180. Following the first 16 bytes is the part of the header called the
  181. "index".  The index is made of up "index entries", one for each entry
  182. in the header.  Each index entry contains four int32 quantities.  In
  183. order, they are: tag, type, offset, count.  In the above example, we
  184. have tag=1000, type=6, offset=0, count=1.  By looking up the the tag
  185. in lib/rpmlib.h we can see that this entry is for the package name.
  186. The type of the entry is a STRING.  The offset is an offset from the
  187. start of the data part of the header to the data associated with this
  188. entry.  The count indicates that there is only one string associated
  189. with the entry (which we really already knew since STRING types are
  190. not allowed to have a count greater than 1).
  191.  
  192. In our example there would be 32 such 16-byte index entries, followed
  193. by the data section:
  194.  
  195. 00000210: 72 70 6d 00 32 2e 31 2e 32 00 31 00 52 65 64 20    rpm.2.1.2.1.Red 
  196. 00000220: 48 61 74 20 50 61 63 6b 61 67 65 20 4d 61 6e 61    Hat Package Mana
  197. 00000230: 67 65 72 00 31 e7 cb b4 73 63 68 72 6f 65 64 65    ger.1...schroede
  198. 00000240: 72 2e 72 65 64 68 61 74 2e 63 6f 6d 00 00 00 00    r.redhat.com....
  199. ...
  200. 00000970: 6c 69 62 63 2e 73 6f 2e 35 00 6c 69 62 64 62 2e    libc.so.5.libdb.
  201. 00000980: 73 6f 2e 32 00 00                                  so.2..
  202.  
  203. The data section begins at byte 528 (4 magic, 4 reserved, 4 index
  204. entry count, 4 data byte count, 16 * 32 index entries).  At offset 0,
  205. bytes 528-531 are "rpm" plus a null byte, which is the data for the
  206. first index entry (the package name).  Following is is the data for
  207. each of the other entries.  Each string is null terminated, the strings
  208. in a STRING_ARRAY are also null terminated and are place one after
  209. another.  The integer types are aligned to appropriate byte boundaries,
  210. so that the data of INT64 type starts on an 8 byte boundary, INT32
  211. type starts on a 4 byte boundary, and an INT16 type starts on a 2 byte
  212. boundary.  For example:
  213.  
  214. 00000060: 00 00 03 ef 00 00 00 06 00 00 00 28 00 00 00 01    ................
  215. 00000070: 00 00 03 f1 00 00 00 04 00 00 00 40 00 00 00 01    ................
  216. ...
  217. 00000240: 72 2e 72 65 64 68 61 74 2e 63 6f 6d 00 00 00 00    r.redhat.com....
  218. 00000250: 00 09 9b 31 52 65 64 20 48 61 74 20 4c 69 6e 75    ....Red Hat Linu
  219.  
  220. Index entry number 6 is the BUILDHOST, of type STRING.  Index entry
  221. number 7 is the SIZE, of type INT32.  The corresponding data for entry
  222. 6 end at byte 588 with "....redhat.com\0".  The next piece of data
  223. could start at byte 589, byte that is an improper boundary for an INT32.
  224. As a result, 3 null bytes are inserted and the date for the SIZE actually
  225. starts at byte 592: "00 09 9b 31", which is 629553).
  226.  
  227. Tools
  228. -----
  229.  
  230. The tools directory in the RPM sources contains a number of small
  231. programs that use the RPM library to pick apart packages.  These
  232. tools are mostly used for debugging, but can also be used to help
  233. you understand the internals of the RPM package format.
  234.  
  235.     rpmlead        - extracts the Lead from a package
  236.     rpmsignature    - extracts the Signature from a package
  237.     rpmheader    - extracts the Header from a package
  238.     rpmarchive    - extracts the Archive from a package
  239.     dump        - displays a header structure in readable format
  240.  
  241. Given a package foo.rpm you might try:
  242.  
  243.     rpmlead foo.rpm | od -x
  244.     rpmsignature foo.rpm | dump
  245.     rpmheader foo.rpm | dump
  246.     rpmarchive foo.rpm | zcat | cpio --list
  247.