Some comments.

diff --git a/src/kdm.h b/src/kdm.h
index 32269aedb0bed227ce787e768e0a3f80139be9e2..597088ed2fd4c79105c6814621e01dc94653a8af 100644 (file)
--- a/src/kdm.h
+++ b/src/kdm.h
@@ -17,6 +17,10 @@
 
 */
 
+/** @file  src/kdm.h
+ *  @brief Handling of Key Delivery Messages (KDMs).
+ */
+
 #ifndef LIBDCP_KDM_H
 #define LIBDCP_KDM_H
 
@@ -36,14 +40,40 @@ class Signer;
 class Certificate;
 class CPL;
 
-/** A single key for encrypting or decrypting an MXF.  One or more of these
- *  are delivered in a KDM.
+/** @class KDMKey
+ *  @brief A single key (and associated metadata) for encrypting or decrypting an MXF.
+ *
+ *  One or more of these are delivered (themselves encrypted) in a KDM.  The following
+ *  data is collected into a block:
+ *
+ *  A structure ID (a magic value specified by the standard)
+ *  The thumbprint of the KDM signer's certificate.
+ *  The CPL ID.
+ *  The key ID.
+ *  Validity start and end times.
+ *  The key itself
+ *
+ *  This data block is then encrypted using the projector's public key, so that
+ *  only the target projector can decrypt block.
  */
 class KDMKey
 {
 public:
-       KDMKey (uint8_t const *, int);
-
+       /** Create a KDMKey from the raw block that is encrypted in the KDM's CipherData.
+        *  @param raw Pointer to data block (134 bytes for interop, 138 bytes for SMPTE).
+        *  @param len Length of the data block in bytes.
+        */
+       KDMKey (uint8_t const * raw, int len);
+
+       /** Create a KDMKey from its constituent parts.
+        *  @param signer Signer for the KDM.
+        *  @param cpl_id ID of the CPL that the KDM is for.
+        *  @param key_type Type of data that this key is for (MDIK for image, MDAK for audio, ...)
+        *  @param key_id ID of this key.
+        *  @param from Valid-from time.
+        *  @param until Valid-until time.
+        *  @param key The key itself.
+        */
        KDMKey (
                boost::shared_ptr<const Signer> signer,
                std::string cpl_id, std::string key_type, std::string key_id, boost::posix_time::ptime from, boost::posix_time::ptime until, Key key
@@ -53,27 +83,35 @@ public:
 
        KDMKey& operator= (KDMKey const &);
 
+       /** @return ID of the CPL that the KDM is for */
        std::string cpl_id () const {
                return _cpl_id;
        }
        
+       /** @return ID of the key */
        std::string key_id () const {
                return _key_id;
        }
 
+       /** @return start of the validity period as a string */
        std::string not_valid_before () const {
                return _not_valid_before;
        }
 
+       /** @return end of the validity period as a string */
        std::string not_valid_after () const {
                return _not_valid_after;
        }
 
+       /** @return the key itself */
        Key key () const {
                return _key;
        }
 
-       std::string encrypted_base64 (boost::shared_ptr<const Certificate>) const;
+       /** @param cert Cerfificate.
+        *  @return The data block encrypted with a certificate's public key and converted to base 64.
+        */
+       std::string encrypted_base64 (boost::shared_ptr<const Certificate> cert) const;
        
 private:
        void get (uint8_t *, uint8_t const **, int) const;
@@ -92,28 +130,60 @@ private:
        Key _key;
 };
 
+/** @class KDM
+ *  @brief A class representing a Key Delivery Message (KDM).
+ *
+ *  A KDM wraps one or more content keys (which we wrap into KDMKey objects) and various
+ *  other metadata.  This class can read and decrypt existing KDMs (provided you have
+ *  the private key that the KDM was targeted at).  It can also create new KDMs for
+ *  a given CPL.
+ */
 class KDM
 {
 public:
-       KDM (boost::filesystem::path, boost::filesystem::path);
-
+       /** Load and decrypt a KDM.  After this constructor the KDMKeys can be read
+        *  and used to decrypt MXFs.
+        *
+        *  @param kdm KDM file name.
+        *  @param private_key Private key file name.
+        */
+       KDM (boost::filesystem::path kdm, boost::filesystem::path private_key);
+
+       /** Create a new KDM.
+        *  @param cpl CPL that the KDM is for.
+        *  @param signer Certificate chain to sign the KDM with.
+        *  @param recipient_cert Certificate of the projector that this KDM is targeted at.
+        *  @param not_valid_before Start of validity period.
+        *  @param not_valid_after End of validity period.
+        *  @param annotation_text Text for the <AnnotationText> node.
+        *  @param issue_date Text for the <IssueDate> node.
+        */
        KDM (
-               boost::shared_ptr<const CPL> cpl, boost::shared_ptr<const Signer>, boost::shared_ptr<const Certificate> recipient_cert,
+               boost::shared_ptr<const CPL> cpl, boost::shared_ptr<const Signer> signer, boost::shared_ptr<const Certificate> recipient_cert,
                boost::posix_time::ptime not_valid_before, boost::posix_time::ptime not_valid_after,
                std::string annotation_text, std::string issue_date
                );
 
+       /** @return The unencrypted content keys from this KDM */
        std::list<KDMKey> keys () const {
                return _keys;
        }
 
-       void as_xml (boost::filesystem::path) const;
+       /** Write this KDM to a file.
+        *  @param file File to write to.
+        */
+       void as_xml (boost::filesystem::path file) const;
+
+       /** Obtain this KDM as an XML string.
+        *  @return XML string.
+        */
        std::string as_xml () const;
 
 private:
        /** Unencrypted MXF content keys */
        std::list<KDMKey> _keys;
 
+       /** The KDM's contents, mapped 1:1-ish to the XML */
        boost::shared_ptr<xml::DCinemaSecurityMessage> xml_kdm;
 };
 

diff --git a/src/key.h b/src/key.h
index fbadfd33ee79e639dc108fffe23d0126ea80b8fa..d0286627cb92cfc09b2ed8705b4c425d242a5c83 100644 (file)
--- a/src/key.h
+++ b/src/key.h
@@ -17,6 +17,10 @@
 
 */
 
+/** @file  src/key.h
+ *  @brief Class to hold a key for encrypting MXFs.
+ */
+
 #ifndef LIBDCP_KEY_H
 #define LIBDCP_KEY_H
 
@@ -24,7 +28,9 @@
 
 namespace libdcp {
 
-/** A key for encrypting MXFs */
+/** @class Key
+ *  @brief A key for encrypting MXFs.
+ */
 class Key
 {
 public:
@@ -42,10 +48,12 @@ public:
 
        Key& operator= (Key const &);
 
-       uint8_t* value () const {
+       /** @return Raw key value */
+       uint8_t const * value () const {
                return _value;
        }
 
+       /** @return Key value as a hexadecimal string */
        std::string hex () const;
 
 private: