aboutsummaryrefslogtreecommitdiffstats
path: root/include/cipherpack
diff options
context:
space:
mode:
Diffstat (limited to 'include/cipherpack')
-rw-r--r--include/cipherpack/cipherpack.hpp136
1 files changed, 75 insertions, 61 deletions
diff --git a/include/cipherpack/cipherpack.hpp b/include/cipherpack/cipherpack.hpp
index 5bdd9b0..49ce43e 100644
--- a/include/cipherpack/cipherpack.hpp
+++ b/include/cipherpack/cipherpack.hpp
@@ -39,69 +39,71 @@
#include <jau/environment.hpp>
#include <jau/java_uplink.hpp>
-/**
- * @anchor cipherpack_overview
- * ### Cipherpack Overview
- * Cipherpack, a secure packaging utility utilizing RSA encryption and signatures to ensure
- * privacy and authenticity of the package's source.
- *
- * The package's header handle the personalized public- and private-key mechanism,
- * securing the high-performance symmetric encryption for the high volume payload.
- *
- * Implementation uses an Authenticated Encryption with Additional Data (AEAD) encryption+MAC cipher algo,
- * i.e. {@link cipherpack::constants::aead_cipher_algo}.
- *
- * ### Cipherpack Implementation
- * #### Implementation Status
- * READY TO USE
- *
- * #### Cipherpack Operations
- * The following RSA encryption + signature and symmetric payload operations are performed:
- * - Writing a DER Header-1, containing the encrypted symmetric file-keys for each public terminal key and further {@link PackInfo} details.
- * - Writing a DER Header-2, containing the DER-Header-1 signature using.
- * - The encrypted payload, i.e. the ciphertext using the symmetric file-key for encryption + MAC via AEAD `ChaCha20Poly1305`.
- *
- * Implementation performs all operation `in-place` without redundant copies.
- *
- * @anchor cipherpack_stream
- * #### Cipherpack Data Stream
- * The cipherpack stream will be produced as follows:
- * ```
- * DER Header 1 {
- * ASN1_Type::OctetString package_magic
- * ASN1_Type::OctetString target_path // designated target path for file
- * ASN1_Type::Integer content_size // plain content size, i.e. decrypted payload
- * ASN1_Type::Integer creation_timestamp_sec
- * ASN1_Type::OctetString intention // designated intention of payload for application
- * ASN1_Type::OctetString payload_version
- * ASN1_Type::OctetString payload_version_parent
- * ASN1_Type::OctetString pk_type // public-key type: "RSA"
- * ASN1_Type::OctetString pk_fingerprt_hash_algo // public-key fingerprint hash: "SHA-256"
- * ASN1_Type::OctetString pk_enc_padding_algo // public-key encryption padding: "OAEP"
- * ASN1_Type::OctetString pk_enc_hash_algo // public-key encryption hash: "SHA-256"
- * ASN1_Type::OctetString pk_sign_algo // "EMSA1(SHA-256)",
- * ASN1_Type::ObjectId sym_enc_mac_oid // "ChaCha20Poly1305",
- * ASN1_Type::OctetString nonce,
- * ASN1_Type::OctetString fingerprt_host // fingerprint of public host key used for header signature
- * ASN1_Type::Integer encrypted_fkey_count, // number of encrypted file-keys
- * ASN1_Type::OctetString fingerprt_term_1, // fingerprint of public terminal key_1 used for encrypted_fkey_term_1
- * ASN1_Type::OctetString encrypted_fkey_term_1, // encrypted file-key with public terminal key_1, decrypted with secret terminal key_1
- * ASN1_Type::OctetString fingerprt_term_2, // fingerprint of public terminal key_1 used for encrypted_fkey_term_2
- * ASN1_Type::OctetString encrypted_fkey_term_2, // encrypted file-key with public terminal key_1, decrypted with secret terminal key_1
- * ....
- * },
- * DER Header 2 {
- * ASN1_Type::OctetString header_sign_host // signed with secret host key and using public host key to verify, matching fingerprt_host
- * },
- * uint8_t encrypted_data[]
- * ```
- *
- * @see encryptThenSign()
- * @see checkSignThenDecrypt()
- *
- */
namespace cipherpack {
+ /** @defgroup CipherpackAPI Cipherpack General User Level API
+ * General User level Cipherpack API types and functionality, see @ref cipherpack_stream "Cipherpack Data Stream",
+ *
+ * @anchor cipherpack_overview
+ * ### Cipherpack Overview
+ * Cipherpack, a secure packaging utility utilizing RSA encryption and signatures to ensure
+ * privacy and authenticity of the package's source.
+ *
+ * The package's header handle the personalized public- and private-key mechanism,
+ * securing the high-performance symmetric encryption for the high volume payload.
+ *
+ * Implementation uses an Authenticated Encryption with Additional Data (AEAD) encryption+MAC cipher algo,
+ * i.e. {@link cipherpack::constants::aead_cipher_algo}.
+ *
+ * ### Cipherpack Implementation
+ * #### Implementation Status
+ * READY TO USE
+ *
+ * #### Cipherpack Operations
+ * The following RSA encryption + signature and symmetric payload operations are performed:
+ * - Writing a DER Header-1, containing the encrypted symmetric file-keys for each public terminal key and further {@link PackInfo} details.
+ * - Writing a DER Header-2, containing the DER-Header-1 signature using.
+ * - The encrypted payload, i.e. the ciphertext using the symmetric file-key for encryption + MAC via AEAD `ChaCha20Poly1305`.
+ *
+ * Implementation performs all operation `in-place` without redundant copies.
+ *
+ * @anchor cipherpack_stream
+ * #### Cipherpack Data Stream
+ * The cipherpack stream will be produced as follows:
+ * ```
+ * DER Header 1 {
+ * ASN1_Type::OctetString package_magic
+ * ASN1_Type::OctetString target_path // designated target path for file
+ * ASN1_Type::Integer content_size // plain content size, i.e. decrypted payload
+ * ASN1_Type::Integer creation_timestamp_sec
+ * ASN1_Type::OctetString intention // designated intention of payload for application
+ * ASN1_Type::OctetString payload_version
+ * ASN1_Type::OctetString payload_version_parent
+ * ASN1_Type::OctetString pk_type // public-key type: "RSA"
+ * ASN1_Type::OctetString pk_fingerprt_hash_algo // public-key fingerprint hash: "SHA-256"
+ * ASN1_Type::OctetString pk_enc_padding_algo // public-key encryption padding: "OAEP"
+ * ASN1_Type::OctetString pk_enc_hash_algo // public-key encryption hash: "SHA-256"
+ * ASN1_Type::OctetString pk_sign_algo // "EMSA1(SHA-256)",
+ * ASN1_Type::ObjectId sym_enc_mac_oid // "ChaCha20Poly1305",
+ * ASN1_Type::OctetString nonce,
+ * ASN1_Type::OctetString fingerprt_host // fingerprint of public host key used for header signature
+ * ASN1_Type::Integer encrypted_fkey_count, // number of encrypted file-keys
+ * ASN1_Type::OctetString fingerprt_term_1, // fingerprint of public terminal key_1 used for encrypted_fkey_term_1
+ * ASN1_Type::OctetString encrypted_fkey_term_1, // encrypted file-key with public terminal key_1, decrypted with secret terminal key_1
+ * ASN1_Type::OctetString fingerprt_term_2, // fingerprint of public terminal key_1 used for encrypted_fkey_term_2
+ * ASN1_Type::OctetString encrypted_fkey_term_2, // encrypted file-key with public terminal key_1, decrypted with secret terminal key_1
+ * ....
+ * },
+ * DER Header 2 {
+ * ASN1_Type::OctetString header_sign_host // signed with secret host key and using public host key to verify, matching fingerprt_host
+ * },
+ * uint8_t encrypted_data[]
+ * ```
+ *
+ * @see encryptThenSign()
+ * @see checkSignThenDecrypt()
+ * @{
+ */
#define JAVA_MAIN_PACKAGE "org/cipherpack/"
@@ -468,6 +470,18 @@ namespace cipherpack {
CipherpackListenerRef listener,
const std::string destination_fname = "");
+ /**@}*/
+
} // namespace cipherpack
+ /** \example commandline.cpp
+ * This is the commandline version to convert a source from and to a cipherpack, i.e. encrypt and decrypt.
+ */
+
+ /** \example test_01_cipherpack.cpp
+ * Unit test, testing encrypting to and decrypting from a cipherpack stream using different sources.
+ *
+ * Unit test also covers error cases.
+ */
+
#endif /* JAU_CIPHERPACK_HPP_ */