Fully qualify the header filenames for doxygen.

[shibboleth/cpp-xmltooling.git] / xmltooling / encryption / Encrypter.h

diff --git a/xmltooling/encryption/Encrypter.h b/xmltooling/encryption/Encrypter.h
index 1bf6945..1c85762 100644 (file)
--- a/xmltooling/encryption/Encrypter.h
+++ b/xmltooling/encryption/Encrypter.h
@@ -51,7 +51,10 @@ namespace xmlencryption {
      * Summing up, if KeyEncryptionParams are used, a raw key must be available or the
      * key can be generated when the encryption algorithm itself is a standard one. If
      * no KeyEncryptionParams are supplied, then the key must be supplied either in raw
-     * or object form. 
+     * or object form.
+     *
+     * Finally, when encrypting data, the key transport algorithm can be left blank to
+     * derive it from the data encryption algorithm.
      */
     class XMLTOOL_API Encrypter
     {
@@ -61,7 +64,6 @@ namespace xmlencryption {
          * Structure to collect encryption requirements.
          */
         struct XMLTOOL_API EncryptionParams {
-            
             /**
              * Constructor.
              *
@@ -85,42 +87,51 @@ namespace xmlencryption {
             }
 
             ~EncryptionParams() {}
-        private:
+
+            /** Data encryption algorithm. */
             const XMLCh* m_algorithm;
+            
+            /** Buffer containing encryption key. */
             const unsigned char* m_keyBuffer;
+
+            /** Size of buffer. */
             unsigned int m_keyBufferSize;
+
+            /** Credential containing the encryption key. */
             const xmltooling::Credential* m_credential;
+
+            /** Flag limiting the size of the encrypted XML representation. */
             bool m_compact;
-            
-            friend class Encrypter;
         };
         
         /**
          * Structure to collect key wrapping/transport requirements.
          */
         struct XMLTOOL_API KeyEncryptionParams {
-            
             /**
              * Constructor.
              * 
              * @param credential    a Credential supplying the key encryption key
-             * @param algorithm     the XML Encryption key wrapping or transport algorithm constant
+             * @param algorithm     XML Encryption key wrapping or transport algorithm constant
              * @param recipient     optional name of recipient of encrypted key
              */
             KeyEncryptionParams(
                 const xmltooling::Credential& credential,
-                const XMLCh* algorithm,
+                const XMLCh* algorithm=NULL,
                 const XMLCh* recipient=NULL
                 ) : m_credential(credential), m_algorithm(algorithm), m_recipient(recipient) {
             }
         
             ~KeyEncryptionParams() {}
-        private:
+
+            /** Credential containing key encryption key. */
             const xmltooling::Credential& m_credential;
+
+            /** Key transport or wrapping algorithm. */
             const XMLCh* m_algorithm;
+
+            /** Name of recipient that owns the key encryption key. */
             const XMLCh* m_recipient;
-            
-            friend class Encrypter;
         };
     
         Encrypter() : m_cipher(NULL) {}
@@ -142,7 +153,9 @@ namespace xmlencryption {
          * @param kencParams    key encryption settings, or NULL
          * @return a stand-alone EncryptedData object, unconnected to the source DOM 
          */
-        EncryptedData* encryptElement(DOMElement* element, EncryptionParams& encParams, KeyEncryptionParams* kencParams=NULL);
+        EncryptedData* encryptElement(
+            xercesc::DOMElement* element, EncryptionParams& encParams, KeyEncryptionParams* kencParams=NULL
+            );
 
         /**
          * Encrypts the supplied element's children and returns the resulting object.
@@ -159,7 +172,9 @@ namespace xmlencryption {
          * @param kencParams    key encryption settings, or NULL
          * @return a stand-alone EncryptedData object, unconnected to the source DOM 
          */
-        EncryptedData* encryptElementContent(DOMElement* element, EncryptionParams& encParams, KeyEncryptionParams* kencParams=NULL);
+        EncryptedData* encryptElementContent(
+            xercesc::DOMElement* element, EncryptionParams& encParams, KeyEncryptionParams* kencParams=NULL
+            );
 
         /**
          * Encrypts the supplied input stream and returns the resulting object.
@@ -187,7 +202,18 @@ namespace xmlencryption {
          * @param compact       true iff the encrypted representation should be made as small as possible
          * @return a stand-alone EncryptedKey object, unconnected to any DOM 
          */
-        EncryptedKey* encryptKey(const unsigned char* keyBuffer, unsigned int keyBufferSize, KeyEncryptionParams& kencParams, bool compact=false);
+        EncryptedKey* encryptKey(
+            const unsigned char* keyBuffer, unsigned int keyBufferSize, KeyEncryptionParams& kencParams, bool compact=false
+            );
+        
+        /**
+         * Maps a data encryption algorithm to an appropriate key transport algorithm to use.
+         * 
+         * @param credential    the key encryption key
+         * @param encryptionAlg data encryption algorithm
+         * @return a key transport algorithm
+         */
+        static const XMLCh* getKeyTransportAlgorithm(const xmltooling::Credential& credential, const XMLCh* encryptionAlg);
         
     private:
         void checkParams(EncryptionParams& encParams, KeyEncryptionParams* kencParams);