X-Git-Url: https://git.carlh.net/gitweb/?a=blobdiff_plain;f=src%2Fkdm.h;h=597088ed2fd4c79105c6814621e01dc94653a8af;hb=e8530ea06f0b0883e5e19dd18beed70732ac5d3c;hp=ba17ee6b1fcf8e1028afc26567175d3560664783;hpb=b405b414993458babbb4532ddeeef9928ec7c06e;p=libdcp.git

diff --git a/src/kdm.h b/src/kdm.h
index ba17ee6b..597088ed 100644
--- 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,44 +40,78 @@ 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_id, boost::posix_time::ptime from, boost::posix_time::ptime until, Key key
+		std::string cpl_id, std::string key_type, std::string key_id, boost::posix_time::ptime from, boost::posix_time::ptime until, Key key
 		);
 	
 	KDMKey (KDMKey const &);
 
 	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;
 };