QiPki

QiPki is an effort to create Java developper tools to build cryptography into applications and heading towards building a suite of packaged cryptography services.

Development tries to follow principles learned from DDD, DCI, ReST and more using the Qi4j engine and framework.

Use the Crypto API

The main goal of The Crypto API is to lower the developer pain by wrapping underlying tools with nice, strongly typed APIs, easing testability, mockability and usage with dependency injection tools like Guice, CDI or Qi4j.

Embedd a CA

Learn how to embedd a fully working CA inside your Java application. It's basically a matter of instanciating the good objects and using a simple API.

Status & Roadmap

Learn where the project is, where it comes from and where it's headed.

See what is in the present feature set and what is coming.

Participate

QiPki is published under the open-source Apache Licence.

The project is quite ambitious and needs some help, see what you could do to help it grow.

QiPki is licenced under the Apache Licence Version 2.0


                                 Apache License
                           Version 2.0, January 2004
                        http://www.apache.org/licenses/

   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

   1. Definitions.

      "License" shall mean the terms and conditions for use, reproduction,
      and distribution as defined by Sections 1 through 9 of this document.

      "Licensor" shall mean the copyright owner or entity authorized by
      the copyright owner that is granting the License.

      "Legal Entity" shall mean the union of the acting entity and all
      other entities that control, are controlled by, or are under common
      control with that entity. For the purposes of this definition,
      "control" means (i) the power, direct or indirect, to cause the
      direction or management of such entity, whether by contract or
      otherwise, or (ii) ownership of fifty percent (50%) or more of the
      outstanding shares, or (iii) beneficial ownership of such entity.

      "You" (or "Your") shall mean an individual or Legal Entity
      exercising permissions granted by this License.

      "Source" form shall mean the preferred form for making modifications,
      including but not limited to software source code, documentation
      source, and configuration files.

      "Object" form shall mean any form resulting from mechanical
      transformation or translation of a Source form, including but
      not limited to compiled object code, generated documentation,
      and conversions to other media types.

      "Work" shall mean the work of authorship, whether in Source or
      Object form, made available under the License, as indicated by a
      copyright notice that is included in or attached to the work
      (an example is provided in the Appendix below).

      "Derivative Works" shall mean any work, whether in Source or Object
      form, that is based on (or derived from) the Work and for which the
      editorial revisions, annotations, elaborations, or other modifications
      represent, as a whole, an original work of authorship. For the purposes
      of this License, Derivative Works shall not include works that remain
      separable from, or merely link (or bind by name) to the interfaces of,
      the Work and Derivative Works thereof.

      "Contribution" shall mean any work of authorship, including
      the original version of the Work and any modifications or additions
      to that Work or Derivative Works thereof, that is intentionally
      submitted to Licensor for inclusion in the Work by the copyright owner
      or by an individual or Legal Entity authorized to submit on behalf of
      the copyright owner. For the purposes of this definition, "submitted"
      means any form of electronic, verbal, or written communication sent
      to the Licensor or its representatives, including but not limited to
      communication on electronic mailing lists, source code control systems,
      and issue tracking systems that are managed by, or on behalf of, the
      Licensor for the purpose of discussing and improving the Work, but
      excluding communication that is conspicuously marked or otherwise
      designated in writing by the copyright owner as "Not a Contribution."

      "Contributor" shall mean Licensor and any individual or Legal Entity
      on behalf of whom a Contribution has been received by Licensor and
      subsequently incorporated within the Work.

   2. Grant of Copyright License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      copyright license to reproduce, prepare Derivative Works of,
      publicly display, publicly perform, sublicense, and distribute the
      Work and such Derivative Works in Source or Object form.

   3. Grant of Patent License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      (except as stated in this section) patent license to make, have made,
      use, offer to sell, sell, import, and otherwise transfer the Work,
      where such license applies only to those patent claims licensable
      by such Contributor that are necessarily infringed by their
      Contribution(s) alone or by combination of their Contribution(s)
      with the Work to which such Contribution(s) was submitted. If You
      institute patent litigation against any entity (including a
      cross-claim or counterclaim in a lawsuit) alleging that the Work
      or a Contribution incorporated within the Work constitutes direct
      or contributory patent infringement, then any patent licenses
      granted to You under this License for that Work shall terminate
      as of the date such litigation is filed.

   4. Redistribution. You may reproduce and distribute copies of the
      Work or Derivative Works thereof in any medium, with or without
      modifications, and in Source or Object form, provided that You
      meet the following conditions:

      (a) You must give any other recipients of the Work or
          Derivative Works a copy of this License; and

      (b) You must cause any modified files to carry prominent notices
          stating that You changed the files; and

      (c) You must retain, in the Source form of any Derivative Works
          that You distribute, all copyright, patent, trademark, and
          attribution notices from the Source form of the Work,
          excluding those notices that do not pertain to any part of
          the Derivative Works; and

      (d) If the Work includes a "NOTICE" text file as part of its
          distribution, then any Derivative Works that You distribute must
          include a readable copy of the attribution notices contained
          within such NOTICE file, excluding those notices that do not
          pertain to any part of the Derivative Works, in at least one
          of the following places: within a NOTICE text file distributed
          as part of the Derivative Works; within the Source form or
          documentation, if provided along with the Derivative Works; or,
          within a display generated by the Derivative Works, if and
          wherever such third-party notices normally appear. The contents
          of the NOTICE file are for informational purposes only and
          do not modify the License. You may add Your own attribution
          notices within Derivative Works that You distribute, alongside
          or as an addendum to the NOTICE text from the Work, provided
          that such additional attribution notices cannot be construed
          as modifying the License.

      You may add Your own copyright statement to Your modifications and
      may provide additional or different license terms and conditions
      for use, reproduction, or distribution of Your modifications, or
      for any such Derivative Works as a whole, provided Your use,
      reproduction, and distribution of the Work otherwise complies with
      the conditions stated in this License.

   5. Submission of Contributions. Unless You explicitly state otherwise,
      any Contribution intentionally submitted for inclusion in the Work
      by You to the Licensor shall be under the terms and conditions of
      this License, without any additional terms or conditions.
      Notwithstanding the above, nothing herein shall supersede or modify
      the terms of any separate license agreement you may have executed
      with Licensor regarding such Contributions.

   6. Trademarks. This License does not grant permission to use the trade
      names, trademarks, service marks, or product names of the Licensor,
      except as required for reasonable and customary use in describing the
      origin of the Work and reproducing the content of the NOTICE file.

   7. Disclaimer of Warranty. Unless required by applicable law or
      agreed to in writing, Licensor provides the Work (and each
      Contributor provides its Contributions) on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
      implied, including, without limitation, any warranties or conditions
      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
      PARTICULAR PURPOSE. You are solely responsible for determining the
      appropriateness of using or redistributing the Work and assume any
      risks associated with Your exercise of permissions under this License.

   8. Limitation of Liability. In no event and under no legal theory,
      whether in tort (including negligence), contract, or otherwise,
      unless required by applicable law (such as deliberate and grossly
      negligent acts) or agreed to in writing, shall any Contributor be
      liable to You for damages, including any direct, indirect, special,
      incidental, or consequential damages of any character arising as a
      result of this License or out of the use or inability to use the
      Work (including but not limited to damages for loss of goodwill,
      work stoppage, computer failure or malfunction, or any and all
      other commercial damages or losses), even if such Contributor
      has been advised of the possibility of such damages.

   9. Accepting Warranty or Additional Liability. While redistributing
      the Work or Derivative Works thereof, You may choose to offer,
      and charge a fee for, acceptance of support, warranty, indemnity,
      or other liability obligations and/or rights consistent with this
      License. However, in accepting such obligations, You may act only
      on Your own behalf and on Your sole responsibility, not on behalf
      of any other Contributor, and only if You agree to indemnify,
      defend, and hold each Contributor harmless for any liability
      incurred by, or claims asserted against, such Contributor by reason
      of your accepting any such warranty or additional liability.

   END OF TERMS AND CONDITIONS

                

Before choosing between the latest release or a development build, be sure to check out the status and roadmap of the project.

Latest release

Artifacts

QiPki artifacts are synced into maven central and can be downloaded from there.

Download QiPki

Packaged release

Latest release do not include the packaged UNIX daemon, see the development builds below for now.

Development builds

QiPki use the awesome DEV@cloud service gracefully provided by Cloudbees to FOSS projects.

Here is a POM snippet to add the snapshot repository:

<repository>
    <id>qipki-snapshots-repository</id>
    <url>http://repository-qipki.forge.cloudbees.com/snapshot/</url>
    <snapshots>
        <enabled>true</enabled>
    </snapshots>
</repository>

Current development version is 2.0-SNAPSHOT.

Build QiPki yourself

If you want to go deeper, try to fix an issue you spotted or contribute a new feature, you can build QiPki yourself.

The build system is documented in the build page.

This documentation use unreleased features! See the Roadmap page.

During the QiPki development a comprehensive Crypto API was build and is still enhanced. This library does not try to reinvent the wheel where good wheels are found. It leverages the JCA and BouncyCastle.

The main goal of the Crypto API is to ease the developer pain by wrapping underlying tools with nice, strongly typed APIs and being easily testable, mockable, usable with dependency injection tools like Guice, CDI or Qi4j.

Getting started

You will need java and maven plus a source editor of your choice.

Create a new maven project

Start by creating a new maven project with the following command:

mvn -B archetype:generate -DarchetypeArtifactId=maven-archetype-quickstart -DgroupId=com.mycompany.app -DartifactId=my-app -Dversion=2.0-SNAPSHOT

Replace com.mycompany.app and my-app by the groupId and artifactId you want to use.

This should have created a my-app directory containing an empty java maven project. Now, open the pom.xml file and add this before the <dependencies> section:

<build>
  <plugins>
    <plugin>
      <artifactId>maven-compiler-plugin</artifactId>
      <configuration>
        <source>1.5</source>
        <target>1.5</target>
      </configuration>
    </plugin>
  </plugins>
</build>
<repositories>
  <repository>
      <id>qipki-snapshots-repository</id>
      <url>http://repository-qipki.forge.cloudbees.com/snapshot/</url>
      <snapshots>
          <enabled>true</enabled>
      </snapshots>
  </repository>
</repositories>
Depends on the qipki-crypto module

Add org.codeartisans.qipki:qipki-crypto as dependency to your project inside the <dependencies> section:

<dependency>
  <groupId>org.codeartisans.qipki</groupId>
  <artifactId>qipki-crypto</artifactId>
  <version>2.0-SNAPSHOT</version>
</dependency>

Ensure that everything works by issueing a mvn clean install command.

You can now start using the QiPki Crypto API.

Note that the examples below are automaticaly extracted from actual code, often from unit tests. When applicable, theses examples show two ways to do things: with and without Qi4j. You'll se that the plumbing code provided for integration with Qi4j ease things a lot. Using another DI tool like Guice, CDI or Spring would help in quite the same way.

Digests aka. Hashes

A cryptographic hash function is a deterministic procedure that takes an arbitrary block of data and returns a fixed-size bit string, the (cryptographic) hash value, such that an accidental or intentional change to the data will change the hash value. The data to be encoded is often called the "message," and the hash value is sometimes called the message digest or simply digest.

Cryptographic hash function From Wikipedia, the free encyclopedia

The following code generate hexadecimal encoded hashes of a single string using several algorithms.

// Snippet extracted from DigesterTest.java starting on line 62

private void testDigester( Digester digester )
        throws UnsupportedEncodingException
{
    // Digest messages
    String hexMd5 = digester.hexDigest( MESSAGE, DigestParameters.MD5 );
    String hexSha1 = digester.hexDigest( MESSAGE, DigestParameters.SHA_1 );
    String hexSha256 = digester.hexDigest( MESSAGE, DigestParameters.SHA_256 );
    String hexSha384 = digester.hexDigest( MESSAGE, DigestParameters.SHA_384 );
    String hexSha512 = digester.hexDigest( MESSAGE, DigestParameters.SHA_512 );

    // Test
    assertEquals( EXPECTED_MD5, hexMd5 );
    assertEquals( EXPECTED_SHA_1, hexSha1 );
    assertEquals( EXPECTED_SHA_256, hexSha256 );
    assertEquals( EXPECTED_SHA_384, hexSha384 );
    assertEquals( EXPECTED_SHA_512, hexSha512 );
}

The DigestParameters accept the following options:

Theses options let you make proper password hashing. Here is an example using a random 64 bits salt and 1024 iterations:

// Snippet extracted from DigesterTest.java starting on line 83

public void saltedHashExample()
{
    // A Base64 encoded SHA-256 digest using a 64bit random salt and 1024 iterations
    String base64 = digester.base64Digest( MESSAGE, new DigestParameters( SHA_256, digester.generateSalt( 64 ), 1024 ) );

    // A Hex encoded SHA-256 digest using a 64bit random salt and 1024 iterations
    String hex = digester.hexDigest( MESSAGE, digester.newParamsBuilder().using( SHA_256 ).salted( 64 ).iterations( 1024 ).build() );
}

Symetric cryptography AES for example

Symmetric-key algorithms are a class of algorithms for cryptography that use trivially related, often identical, cryptographic keys for both encryption of plaintext and decryption of ciphertext. The encryption key is trivially related to the decryption key, in that they may be identical or there is a simple transformation to go between the two keys. The keys, in practice, represent a shared secret between two or more parties that can be used to maintain a private information link.

Symmetric-key algorithm From Wikipedia, the free encyclopedia

The following code generates a 128 bits AES key and then use it to cipher a string then to decipher it using CBC mode of operation and PKCS5 padding.

// Snippet extracted from CipherTest.java starting on line 77

private void testAES128( SymetricGenerator symGenerator, CipherFactory cipherFactory )
    throws UnsupportedEncodingException
{
    // AES-128 key generation
    SecretKey key = symGenerator.generateCipheringKey( AES_128 );
    String plainText = "CipherMe";

    // Cipher creation
    SymetricCipher cipher = cipherFactory.newSymetricCipher( AES_CBC_PKCS5 );

    // Cipher and decipher
    byte[] ciphered = cipher.cipher( plainText.getBytes( UTF_8 ), key );
    byte[] deciphered = cipher.decipher( ciphered, key );

    // Test
    assertEquals( plainText, new String( deciphered, UTF_8 ) );
}

The very same operation applied on a data stream:

// Snippet extracted from CipherTest.java starting on line 98

public void testOnStreams()
    throws UnsupportedEncodingException
{
    // AES-128 key generation
    SecretKey key = symGenerator.generateCipheringKey( AES_128 );
    String plainText = "CipherMe in a stream";

    // Cipher creation
    SymetricCipher cipher = cipherFactory.newSymetricCipher( AES_CBC_PKCS5 );

    // Ciphering…
    InputStream inputStream = new ByteArrayInputStream( plainText.getBytes( UTF_8 ) );
    ByteArrayOutputStream outputStream = new ByteArrayOutputStream();

    cipher.cipher( inputStream, outputStream, key );
    byte[] ciphered = outputStream.toByteArray();

    // Deciphering…
    inputStream = new ByteArrayInputStream( ciphered );
    outputStream = new ByteArrayOutputStream();

    cipher.decipher( inputStream, outputStream, key );
    byte[] deciphered = outputStream.toByteArray();

    // Test
    assertEquals( plainText, new String( deciphered, UTF_8 ) );
}

Message Authentication Codes

In cryptography, a message authentication code (often MAC) is a short piece of information used to authenticate a message.

A MAC algorithm, sometimes called a keyed (cryptographic) hash function, accepts as input a secret key and an arbitrary-length message to be authenticated, and outputs a MAC (sometimes known as a tag). The MAC value protects both a message's data integrity as well as its authenticity, by allowing verifiers (who also possess the secret key) to detect any changes to the message content.

Message authentication code From Wikipedia, the free encyclopedia
// Snippet extracted from MacTest.java starting on line 44

@Test
public void testMac()
{
    // Alice & Bob
    SecretKey signingKey = symGenerator.generateSigningKey( HmacSHA256_256 );

    // Alice
    String message = "Oh Bob, MAC me!";
    String aliceMAC = mac.hexMac( message, new HMACParameters( HmacSHA256, signingKey ) );

    System.out.println( "Alice: " + message + " [ " + aliceMAC + " ]" );

    // Bob
    String bobMAC = mac.hexMac( message, new HMACParameters( HmacSHA256, signingKey ) );
    assertEquals( aliceMAC, bobMAC );

    System.out.println( "Bob: Alright Alice!" + " [ " + bobMAC + " ]" );
}

Asymetric-key cryptography

Public-key cryptography refers to a cryptographic system requiring two separate keys, one to lock or encrypt the plaintext, and one to unlock or decrypt the cyphertext. Neither key will do both functions. One of these keys is published or public and the other is kept private. If the lock/encryption key is the one published then the system enables private communication from the public to the unlocking key's owner. If the unlock/decryption key is the one published then the system serves as a signature verifier of documents locked by the owner of the private key.

Asymmetric-key cryptography From Wikipedia, the free encyclopedia

TODO Add examples from the unit tests.

X.509

In cryptography, X.509 is an ITU-T standard for a public key infrastructure (PKI) and Privilege Management Infrastructure (PMI). X.509 specifies, amongst other things, standard formats for public key certificates, certificate revocation lists, attribute certificates, and a certification path validation algorithm.

X.509 From Wikipedia, the free encyclopedia
Distinguished names

The DistinguishedName class hide api complexity needed to handle X.509 distinguished names in the X.500 tradition, especially regarding encoding and special characters escape. The DistinguishdNameTemplate class build on this to provide a convenient way to generate DNs from templates:

// Snippet extracted from DistinguishedNameTemplateTest.java starting on line 39

@Test
public void testDistinguishedNameTemplate()
{
    // Create a template
    String template = "CN=${U_FIRSTNAME} ${U_LASTNAME}, E=${U_EMAIL}, O=${U_ORGANISATION}, "
                      + "OU=Github, 0.9.2342.19200300.100.1.5=${D_SERIALNUMBER}";

    // Prepare context properties
    Map<String, String> context = new HashMap<String, String>();
    context.put( "U_FIRSTNAME", "Paul" );
    context.put( "U_LASTNAME", "Merl,=\"+<>#;\\in" );
    context.put( "U_ORGANISATION", "Codearti€ans" );
    context.put( "U_EMAIL", "paul+zog@nosphere.org" );

    // Build the DistinguishedName instance
    DistinguishedName dn = new DistinguishedNameTemplate( template ).buildDN( context );
    systemOutput( dn );

    // Assert formats
    assertEquals( EXPECTED_RFC1779, dn.toString( RFC1779 ) );
    assertEquals( EXPECTED_RFC1779_and_RFC3383, dn.toString( RFC1779_and_RFC3383 ) );

    assertEquals( EXPECTED_RFC2253, dn.toString( RFC2253 ) );
    assertEquals( EXPECTED_RFC2253_and_RFC3383, dn.toString( RFC2253_and_RFC3383 ) );
    assertEquals( EXPECTED_RFC2253_CANONICAL, dn.toString( RFC2253_CANONICAL ) );

    // Assert formats through BouncyCastle X509Name (does not support RFC1779 formatted Directory Strings)
    assertEquals( EXPECTED_BC_RFC2253, new X509Name( dn.toString( RFC2253 ) ).toString() );
    assertEquals( EXPECTED_BC_RFC2253_and_RFC3383, new X509Name( dn.toString( RFC2253_and_RFC3383 ) ).toString() );
    assertEquals( EXPECTED_BC_RFC2253_CANONICAL, new X509Name( dn.toString( RFC2253_CANONICAL ) ).toString() );
}

I/O

TODO Add examples from the unit tests.

Logging

TODO Explain SLF4J usage and loggers hierarchy

This documentation use unreleased features! See the Roadmap page.

Getting started

You will need java and maven plus a source editor of your choice.

Create a new maven project

Start by creating a new maven project with the following command:

mvn -B archetype:generate -DarchetypeArtifactId=maven-archetype-quickstart -DgroupId=com.mycompany.app -DartifactId=my-app -Dversion=2.0-SNAPSHOT

Replace com.mycompany.app and my-app by the groupId and artifactId you want to use.

This should have created a my-app directory containing an empty java maven project. Now, open the pom.xml file and add this before the <dependencies> section:

<build>
  <plugins>
    <plugin>
      <artifactId>maven-compiler-plugin</artifactId>
      <configuration>
        <source>1.5</source>
        <target>1.5</target>
      </configuration>
    </plugin>
  </plugins>
</build>
<repositories>
  <repository>
      <id>qipki-snapshots-repository</id>
      <url>http://repository-qipki.forge.cloudbees.com/snapshot/</url>
      <snapshots>
          <enabled>true</enabled>
      </snapshots>
  </repository>
</repositories>
Depends on the qipki-ca module

Add org.codeartisans.qipki:qipki-ca as dependency to your project inside the <dependencies> section:

<dependency>
  <groupId>org.codeartisans.qipki</groupId>
  <artifactId>qipki-ca</artifactId>
  <version>2.0-SNAPSHOT</version>
</dependency>

Ensure that everything works by issueing a mvn clean install command.

You can now start using the QiPki Embedded CA.

Embedd
package org.qipki.examples.embeddedca;

import /* ... snip ... */;

public class EmbeddedCaExample
{

    public static void main( String[] args )
    {
        // Instanciate and run the embedded CA application
        QiPkiEmbeddedCa ca = new QiPkiEmbeddedCa( TODO );
        ca.run();
        UnitOfWorkFactory uowf = ca.unitOfWorkFactory();

        // Create a new UnitOfWork
        UnitOfWork uow = uowf.newUnitOfWork();

        // Interract with the CA here using the RootContext
        RootContext<TODO> caCtx = ca.newRootContext();
        // Keep reading for example interactions

        // Apply changes
        try {
            uow.complete();
        } catch ( UnitOfWorkCompletionException ex ) {
            throw new RuntimeException( "Something went wrong" );
        } finally {
            uow.discard(); // No changes are discarded if the UnitOfWork completed successfully
        }

        // Stop gracefully
        ca.stop();
    }

}

TODO Explain this code snippet.

CA context

TODO Explain QiPki DCI implementation.

Create a CA self-signed and stored in a PKCS#12 file

TODO Add examples from the unit tests.

Issue a certificate using a predefined profile

TODO Add examples from the unit tests.

Renew a certificate using a new keypair

TODO Add examples from the unit tests.

Revoke a certificate and consume the generated CRL

TODO Add examples from the unit tests.

Going further

Logging

TODO Explain SLF4J usage and loggers hierarchy

Assemble and configure set the data and logging paths, choose backend implementations

TODO Add examples from the unit tests.

Manage certificate profiles different types of certificates, assignment to CAs

TODO Add examples from the unit tests.

Use escrowed keypairs eg. for digital signature

TODO Add examples from the unit tests.

Configure logging using SLF4J

TODO Add examples from the unit tests.

Expose runtime data through JMX runtime configuration changes, statistics

TODO Add examples from the unit tests.

Status

Latest release, 1.0, contains a usable embedded CA with CRL support. This version uses an embedded instance of Apache Derby to store all of its data, an embedded Sesame based RDF repository for indexing/querying and the filesystem to store keystores and crls.

The following release, probably 1.1-*, will be based on Qi4j 2.0, allows you to choose more store/indexing/querying backend implementations and have a comprehensive set of web user interfaces.

The current codebase is being worked on mainly to implement all the CA interactions as http resources for use over the network. The build already produces a UNIX daemon like packaging.

The HEAD of the source is kept as stable as possible thanks to continuous integration, if you are curious you can take a look at the ca-http-main module output, you'll find a tarball there.

Roadmap

Attention This roadmap is subject to changes without notice as the project grow.

See the detailed roadmap for details.

Who use QiPki?

The first user of QiPki is QiPki. As every component is built to be embeddable, QiPki use this facility to build a new open-source cryptography services suite.

The CryptoAPI is used in several projects while for now the only project using the embeddable CA is the eKeynox suite from Netheos. It's already deployed and used in production in setups involving ten thousands of users/certificates.

QiPki is a young project, till it already is 2 years old. You can read more about it's history, status and roadmap here.

Any kind of help would be useful, from suggestions, bug reports, patches to spotting a typo in this very page :-) We'll welcome any kind of comment, remark, critics about the project, feel free to create a new issue.

Create a new issue

As you certainly already understood, this is Work In Progress, don't expect something with easy setup and comprehensive documentation for now but in case you're already using the embedded API or want to show your support, use the widgets on the right.

Test

You can follow the documentation about the Crypto API usage or on how to embedd a CA. If you want to try the HTTP based CA you'll have to read some code. We hope that the unit tests are readable enough to get you started. Take a look inside the ca-tests submodule, see below for details.

Develop

Git (with the help of Github) empower you to fork a module, hack on the source and share those changes with others. You only have to involve the project team when you are ready to contribute those changes back into the project's master (upstream) branch by sending a pull request. This is the preferred contribution workflow.

Here is a quick summary of the workflow:

  1. If you do not already have one, create a create a github account.
  2. Set up git in your working environment if needed
  3. Fork the QiPki repository to a copy into your github account
  4. Clone your newly forked copy onto your local workspace
  5. Build QiPki from the sources
  6. Make changes and commit one or more times, using a branch would be a good idea, YMMV
  7. Pull later updates from the main repository and rebase them, optional but appreciated :-)
  8. Push your local commits to your private github repo (origin)
  9. Pull request on github