= 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