Changes between Version 1 and Version 2 of CertSig

Timestamp:

Sep 4, 2008, 7:48:15 AM (16 years ago)

Author:

atisu

Comment:

--

CertSig

@@ -1 @@
-foo
+
+= Verifying application signatures using X.509 certificates =
+
+Beside the project owned executable signing keys (code_sign_public, code_sign_private), OpenSSL RSA keys and X.509 certificates (in .pem format) may be used for signing and verification. This page describes how it can be done.
+
+== The .sig file ==
+
+The .sig file beside any aplication binary may hold either the "traditional" signature of the file created with sign_executable, or a mixed version, or only signatures to be verified using certificates. When using either mixed or certificate only version, the .sig file should have the following structure:
+
+{{{
+<signatures>
+    <entry>
+     <thesignature>
+%SIGNATURE_CREATED_WITH_OPENSSL%
+    </thesignature>
+    <subject>%SUBJECT_OF_CERTIFICATE%</subject>
+    <type>%MD5_OR_SHA1%</type>
+    <hash>%HASH_OF_CERTIFICATE%</hash>
+    </entry>
+    <entry>
+      ...
+    </entry>
+    ...
+</signatures>
+<file_signature>
+%SIGNATURE_CREATED_BY_SIGN_EXECUTABLE%
+</file_signature>
+}}}
+
+This structure needs to be filled with the following values:
+
+ * %SIGNATURE_CREATED_WITH_OPENSSL% - a signature created using an OpenSSL RSA key and the MD5 hash function
+ * %SUBJECT_OF_CERTIFICATE% - the subject of the certificate belonging to the key used to sign the binary
+ * %MD5_OR_SHA1% - should containt either 'md5' or 'sha1'. Currently not used, it is assumed that the signature was created using the MD5 hash function.
+ * %HASH_OF_CERTIFICATE% - should contain the hash of the certificate belonging to the key used for signing.
+
+update_versions will know which type of signatures are in any .sig file and add them to xml_doc (in the database) correctly.
+
+== Creating certificates and keys ==
+
+This example will describe how a self-signed certificate can be created. For production sites, no self-signed certificates should be used.
+
+Firs step is to create an RSA key using OpenSSL issue the following command:
+
+{{{
+openssl genrsa -out my.key 1024
+chmod 400 selfsigned.key
+}}}
+
+To create a certificate signing request using the key use the following:
+
+{{{
+openssl req -new -nodes -key my.key -out selfsigned.csr
+}}}
+
+It will ask for some information: country name, state name, locality name, organization, organization unit, your name, email address and a password which is optional.  From the request the self-signed certificate can be created:
+
+{{{
+openssl x509 -req -days 365 -in selfsigned.csr -signkey my.key -out selfsigned.cert
+}}}
+
+This will create a certificate named "selfsigned.cert". To view the metadata incorporated in the certificate
+issue the following:
+
+{{{
+openssl x509 -noout -text -in selfsigned.cert
+}}}
+
+
+== Signing code and getting information from the certificate ==
+
+To sign a file issue the following command:
+
+{{{
+openssl dgst -md5 -sign my.key -out %MYFILE%.sig %MYFILE%
+}}}
+
+This will sign the file %MYFILE% and put the signature in %MYFILE%.sig. This signature file cannot be used yet by BOINC, since it expects a padded and hex converted format. Crypt_prog has been extended to be able to convert between OpenSSL and BOINC formats:
+
+{{{
+crypt_prog -convsig o2b %MYFILE%.sig %MYFILE%.sig.boinc
+}}}
+
+The content of %MYFILE%.sig.boinc can be used to put in the .sig file (to be put in the '%SIGNATURE_CREATED_WITH_OPENSSL%' part).
+
+=== Getting the subject of a certificate ===
+
+The command
+
+{{{
+openssl x509 -noout -in %MYFILE%.cert -subject
+}}}
+
+will print the subject.
+
+=== Getting the hash of a certificate ===
+
+The command
+
+{{{
+openssl x509 -noout -in %MYFILE%.cert -hash
+}}}
+
+will print the hash.
+
+
+== Configuration for the Core Client ==
+
+Using certifiates for verification on clients id disabled by default. The client configuration file (cc_config.xml) has two parameters which control the use of certificates:
+
+{{{
+<cc_config>
+  ...
+  <options>
+    [ <use_certs>0|1</use_certs> ]
+    [ <use_certs_only>0|1</use_certs_only> ]
+    ...
+  </options>
+}}}
+
+Setting use_certs to 1 will enable the use of certificates, and setting use_certs_only to 1 will allow only the verification of application files using certificates.
+
+The client will look for certificates in its data directory in a directory named "certificates/". The certificates should be put there and renamed to %HASH_OF_CERTIFICATE%.<0..X> (e.g.: 72d63c7d.0 ). OpenSSL expects them to be in this format. Numbering should start from 0, and if the hash of two certificates are the same, one of them should be renamed to %HASH_OF_CERTIFICATE%.1 and so on.
+
+
+
+== Limitations ==
+
+ * the <type> field in .sig is not used currently, it is assumed that the hash was created using md5
+
+