|
1 #!perl |
|
2 # Copyright (c) 2000-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
3 # All rights reserved. |
|
4 # This component and the accompanying materials are made available |
|
5 # under the terms of the License "Eclipse Public License v1.0" |
|
6 # which accompanies this distribution, and is available |
|
7 # at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
8 # |
|
9 # Initial Contributors: |
|
10 # Nokia Corporation - initial contribution. |
|
11 # |
|
12 # Contributors: |
|
13 # |
|
14 # Description: |
|
15 # |
|
16 # |
|
17 |
|
18 =head1 Introduction |
|
19 |
|
20 When a release is created with C<makerel> and C<makeenv> it is stored in the releasers local archive. To share this release with other development teams involved in the project it must be exported to a remote release archive (typically hosted on an FTP server) which all teams have access to. |
|
21 |
|
22 This document describes how to configure and use the tools to export a teams releases to the remote archive and import other teams releases from it. |
|
23 |
|
24 =head1 Configuration |
|
25 |
|
26 The F<reltools.ini> and export data files must be set up as described in the F<Installation> document. Typically these files will have already been created for the user so no further editing of them is required. (An archive path file may also be needed, depending on your archive arrangement). |
|
27 |
|
28 Releases exported to the remote site are PGP encrypted for security. To encrypt and decrypt releases a command line PGP tool is used by the tools (defined by the C<pgp_tool> keyword in the F<reltools.ini> file). Both supported PGP clients (GnuPG and NAI PGP) require some configuration before they will work with the tools. |
|
29 |
|
30 =head2 Configuring Network Associates PGP |
|
31 |
|
32 NAI command line PGP (version 6 or 7) must be installed on the users machine. The executable is assumed to have the name C<pgp.exe> and exist somewhere in the users path. |
|
33 |
|
34 PGP encrypts and decrypts files using keys stored on a public and secret key ring. Before using the export and import tools the user must set up their key rings for the project they are working on. If pre-configured keyrings have not been supplied the steps below should be followed: |
|
35 |
|
36 =over 4 |
|
37 |
|
38 =item * |
|
39 |
|
40 To use keys from another keyring first extract the keys with the command |
|
41 |
|
42 pgp -kx <keyid> keyfile |
|
43 |
|
44 If the keyrings are not stored in the default directory then the options C<+PUBRING> or C<+SECRING> are required. For example |
|
45 |
|
46 pgp +PUBRING=keyringPath/pubring.pkr -kx 0x12345678 foo.asc |
|
47 pgp +SECRING=keyringPath/secring.skr -kx 0x87654321 bar.asc |
|
48 |
|
49 Remember to extract both public and private keys. |
|
50 |
|
51 To extract keys using the GUI version of PGP use the export key menu option. If the key is private make sure the "include private keys" check box is selected. |
|
52 |
|
53 =item * |
|
54 |
|
55 Create empty key ring files F<pubring.pkr> and F<secring.skr>. Add key files to these key rings using the command |
|
56 |
|
57 pgp -ka keyfile |
|
58 |
|
59 For example |
|
60 |
|
61 pgp +PUBRING=keyringPath/pubring.pkr -ka somePublicKeyfile.asc |
|
62 pgp +SECRING=keyringPath/secring.skr -ka someSecretKeyfile.asc |
|
63 |
|
64 The project key rings must have the names F<pubring.pkr> and F<secring.skr> but can be stored in any directory. If this is not the default directory used by PGP then the user must set the C<pgp_config_path> keyword in the F<reltools.ini> file to the directory where they are stored. |
|
65 |
|
66 =item * |
|
67 |
|
68 Check that the keys exist on the key ring using the command |
|
69 |
|
70 pgp -kv |
|
71 |
|
72 For example |
|
73 |
|
74 pgp +PUBRING=keyringPath/pubring.pkr -kv |
|
75 pgp +SECRING=keyringPath/secring.skr -kv |
|
76 |
|
77 =back |
|
78 |
|
79 Once the keyrings have been created and populated, the keys must be signed with the users private key so that PGP can encrypt non-interactively (a requirement for the export tools to work). To sign all the keys on the project keyring follow the steps below: |
|
80 |
|
81 =over 4 |
|
82 |
|
83 =item * |
|
84 |
|
85 First set the users private key to be the most trusted introducer and the default signing key. To do this run the command |
|
86 |
|
87 pgp -ke your_private_keyid |
|
88 |
|
89 For example |
|
90 |
|
91 pgp +SECRING=keyringPath/secring.skr -kv |
|
92 |
|
93 Input the passphrase, then answer 'y' to make the key the ultimately trusted introducer and the default signing key. Answer 'n' to the other questions. |
|
94 |
|
95 =item * |
|
96 |
|
97 Sign all the keys on the public key ring with the default signing key by calling the command |
|
98 |
|
99 pgp -ks public_keyid |
|
100 |
|
101 for each public key. For example |
|
102 |
|
103 pgp +PUBRING=keyringPath/pubring.pkr -ks 0x12345678 |
|
104 |
|
105 =back |
|
106 |
|
107 Finally, once the key rings have been created and all the keys on them signed they maybe moved to a directory of the users choice (although the file names must be F<pubring.pkr> and F<secring.skr>) The C<pgp_config_path> keyword value in F<reltools.ini> should then be modified to this path. |
|
108 |
|
109 =head2 Configuring GnuPG |
|
110 |
|
111 The tools have been tested with versions 1.06 and 1.4.7 of GnuPG and assume that the C<gpg.exe> executable exists somewhere in the users path. You can either generate a new key pair or you can import PGP keys. |
|
112 |
|
113 =head3 Generating a New Key Pair |
|
114 |
|
115 To generate a new GPG key pair use the command |
|
116 |
|
117 gpg --gen-key |
|
118 |
|
119 and follow the on screen instructions. |
|
120 |
|
121 =head3 Using existing PGP Keys |
|
122 |
|
123 GnuPG can use key rings created by Network Associates PGP (see above) just rename the files to F<pubring.gpg> and F<secring.gpg>. If the user wishes to create GnuPG key rings then follow the steps below |
|
124 |
|
125 =over 4 |
|
126 |
|
127 =item * |
|
128 |
|
129 Export the keys from a PGP keyring using the method described in the section above |
|
130 |
|
131 =item * |
|
132 |
|
133 Import the keys onto the public and private key rings using the command: |
|
134 |
|
135 gpg --import keyfile |
|
136 |
|
137 For GnuPG 1.06 (but not for GnuPG 1.4.7) an additional flag needs to be set to import private keys. Use the command: |
|
138 |
|
139 gpg --allow-secret-keys --import keyfile |
|
140 |
|
141 If the user wishes to use key rings which are not stored in the default location the '--homedir' option must be used. For example |
|
142 |
|
143 gpg --homedir keyringPath --import somePublicKeyFile.asc |
|
144 |
|
145 As before, if importing private keys using GnuPG 1.06, the '--allow-secret-keys' flag is also needed (this flag is not necessary if using GnuPG 1.4.7). Use the command: |
|
146 |
|
147 gpg --homedir keyringPath --allow-secret-keys --import someSecretKeyFile.asc |
|
148 |
|
149 =item * |
|
150 |
|
151 Check that the keys exist on the key rings using |
|
152 |
|
153 gpg --homedir keyringPath --list-keys |
|
154 gpg --homedir keyringPath --list-secret-keys |
|
155 |
|
156 =back |
|
157 |
|
158 Once the key rings have been created they maybe moved to any directory (keeping the file names as F<pubring.gpg> and F<secring.gpg>). The C<pgp_config_path> keyword value in F<reltools.ini> should then be modified to this path. |
|
159 |
|
160 =head2 PGP vs GPG compatibility |
|
161 |
|
162 When exporting or importing with GPG defined as your 'pgp_tool' , and when using keys provided by PGP which employ a patented algorithm such as IDEA, an appropriate plugin will have to be installed for use by GPG. |
|
163 |
|
164 =head1 Exporting releases |
|
165 |
|
166 To export a single release to the remote site use the C<exportrel> command. For example |
|
167 |
|
168 exportrel mycomp myver -v |
|
169 |
|
170 to export a complete environment use the C<exportenv> command. For example |
|
171 |
|
172 exportenv mycomp myver -v |
|
173 |
|
174 C<exportenv> will attempt to export every release in the environment of mycomp myver. |
|
175 |
|
176 Both commands will only attempt to export a release if it is listed in the export table and does not already exist in the remote archive. |
|
177 Using the C<-f> option will force releases to be exported even if they already exist on the remote site (again this only applies to components existing in the users export table) |
|
178 |
|
179 If the C<-r> option is used and the FTP connection is dropped during the upload of a release, the tools will automatically reconnect to the FTP site and resume the upload. This feature may not be supported by some FTP servers. |
|
180 |
|
181 =head1 Importing releases |
|
182 |
|
183 To import a single release to the remote site use the C<importrel> command. For example |
|
184 |
|
185 importrel mycomp myver -v |
|
186 |
|
187 to import a complete environment use the C<importenv> command. For example |
|
188 |
|
189 importenv mycomp myver -v |
|
190 |
|
191 C<importenv> will attempt to import every release in the environment of mycomp myver. If mycomp myver does not exist in the local archive it will import it, read its environment information and then import the rest of the environment. |
|
192 |
|
193 C<importrel> has a C<-f> option which will force the import of a release even if it already |
|
194 exists in the local archive |
|
195 |
|
196 If the C<-r> option is used and the FTP connection is dropped during the download of a release, the tools will automatically reconnect to the FTP site and resume the download. This feature may not be supported by some FTP servers. |
|
197 |
|
198 =head1 COPYRIGHT |
|
199 |
|
200 Copyright (c) 2000-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
201 All rights reserved. |
|
202 This component and the accompanying materials are made available |
|
203 under the terms of the License "Eclipse Public License v1.0" |
|
204 which accompanies this distribution, and is available |
|
205 at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
206 |
|
207 Initial Contributors: |
|
208 Nokia Corporation - initial contribution. |
|
209 |
|
210 Contributors: |
|
211 |
|
212 Description: |
|
213 |
|
214 |
|
215 =cut |