12 files changed, 22 insertions, 11 deletions
diff --git a/src/lib/pubkey/info.txt b/src/lib/pubkey/info.txt
index d74adddf1..88c29e2f6 100644
--- a/src/lib/pubkey/info.txt
+++ b/src/lib/pubkey/info.txt
@@ -15,6 +15,7 @@ x509_key.cpp
 blinding.h
 pk_algs.h
 pk_keys.h
+pk_ops.h
 pk_ops_fwd.h
 pkcs8.h
 pubkey.h
@@ -23,7 +24,6 @@ x509_key.h
 </header:public>
 
 <header:internal>
-pk_ops.h
 pk_ops_impl.h
 </header:internal>
 
diff --git a/src/lib/pubkey/mce/mce_internal.h b/src/lib/pubkey/mce/mce_internal.h
index 1985c23d2..fb995e758 100644
--- a/src/lib/pubkey/mce/mce_internal.h
+++ b/src/lib/pubkey/mce/mce_internal.h
@@ -14,7 +14,7 @@
 
 #include <botan/secmem.h>
 #include <botan/types.h>
-#include <botan/internal/pk_ops.h>
+#include <botan/pk_ops.h>
 #include <botan/mceliece.h>
 
 namespace Botan {
diff --git a/src/lib/pubkey/pk_keys.cpp b/src/lib/pubkey/pk_keys.cpp
index 22b8cf0c0..3b843cea3 100644
--- a/src/lib/pubkey/pk_keys.cpp
+++ b/src/lib/pubkey/pk_keys.cpp
@@ -6,7 +6,7 @@
 */
 
 #include <botan/pk_keys.h>
-#include <botan/internal/pk_ops.h>
+#include <botan/pk_ops.h>
 #include <botan/der_enc.h>
 #include <botan/oids.h>
 #include <botan/hash.h>
diff --git a/src/lib/pubkey/pk_ops.h b/src/lib/pubkey/pk_ops.h
index 57774c3f4..4a136d90f 100644
--- a/src/lib/pubkey/pk_ops.h
+++ b/src/lib/pubkey/pk_ops.h
@@ -1,5 +1,4 @@
 /*
-* PK Operation Types
 * (C) 2010,2015 Jack Lloyd
 *
 * Botan is released under the Simplified BSD License (see license.txt)
@@ -8,6 +7,17 @@
 #ifndef BOTAN_PK_OPERATIONS_H__
 #define BOTAN_PK_OPERATIONS_H__
 
+/**
+* Ordinary applications should never need to include or use this
+* header. It is exposed only for specialized applications which want
+* to implement new versions of public key crypto without merging them
+* as changes to the library. One actual example of such usage is an
+* application which creates RSA signatures using a custom TPM library.
+* Unless you're doing something like that, you don't need anything
+* here. Instead use pubkey.h which wraps these types safely and
+* provides a stable application-oriented API.
+*/
+
 #include <botan/pk_keys.h>
 #include <botan/secmem.h>
 #include <botan/rng.h>
diff --git a/src/lib/pubkey/pk_ops_impl.h b/src/lib/pubkey/pk_ops_impl.h
index bde119ab4..48552afab 100644
--- a/src/lib/pubkey/pk_ops_impl.h
+++ b/src/lib/pubkey/pk_ops_impl.h
@@ -8,7 +8,7 @@
 #ifndef BOTAN_PK_OPERATION_IMPL_H__
 #define BOTAN_PK_OPERATION_IMPL_H__
 
-#include <botan/internal/pk_ops.h>
+#include <botan/pk_ops.h>
 
 namespace Botan {
 
diff --git a/src/lib/pubkey/pubkey.cpp b/src/lib/pubkey/pubkey.cpp
index 580f990a1..dc98d6551 100644
--- a/src/lib/pubkey/pubkey.cpp
+++ b/src/lib/pubkey/pubkey.cpp
@@ -8,7 +8,7 @@
 #include <botan/der_enc.h>
 #include <botan/ber_dec.h>
 #include <botan/bigint.h>
-#include <botan/internal/pk_ops.h>
+#include <botan/pk_ops.h>
 #include <botan/internal/ct_utils.h>
 
 namespace Botan {
diff --git a/src/lib/pubkey/pubkey.h b/src/lib/pubkey/pubkey.h
index 398db82d2..f80e761dd 100644
--- a/src/lib/pubkey/pubkey.h
+++ b/src/lib/pubkey/pubkey.h
@@ -30,6 +30,7 @@ enum Signature_Format { IEEE_1363, DER_SEQUENCE };
 
 /**
 * Public Key Encryptor
+* This is the primary interface for public key encryption
 */
 class BOTAN_DLL PK_Encryptor
    {
diff --git a/src/lib/pubkey/xmss/xmss_publickey.h b/src/lib/pubkey/xmss/xmss_publickey.h
index 55385b438..b8aa8d920 100644
--- a/src/lib/pubkey/xmss/xmss_publickey.h
+++ b/src/lib/pubkey/xmss/xmss_publickey.h
@@ -23,7 +23,7 @@
 #include <botan/pk_keys.h>
 #include <botan/xmss_parameters.h>
 #include <botan/xmss_wots_parameters.h>
-#include <botan/internal/pk_ops.h>
+#include <botan/pk_ops.h>
 
 namespace Botan {
 
diff --git a/src/lib/pubkey/xmss/xmss_signature_operation.h b/src/lib/pubkey/xmss/xmss_signature_operation.h
index 42cad8f82..bd22f3428 100644
--- a/src/lib/pubkey/xmss/xmss_signature_operation.h
+++ b/src/lib/pubkey/xmss/xmss_signature_operation.h
@@ -17,7 +17,7 @@
 #include <botan/xmss_privatekey.h>
 #include <botan/xmss_address.h>
 #include <botan/xmss_common_ops.h>
-#include <botan/internal/pk_ops.h>
+#include <botan/pk_ops.h>
 #include <botan/internal/xmss_signature.h>
 #include <botan/xmss_wots_publickey.h>
 
diff --git a/src/lib/pubkey/xmss/xmss_verification_operation.h b/src/lib/pubkey/xmss/xmss_verification_operation.h
index 1fa3f24e9..35720f73d 100644
--- a/src/lib/pubkey/xmss/xmss_verification_operation.h
+++ b/src/lib/pubkey/xmss/xmss_verification_operation.h
@@ -16,7 +16,7 @@
 #include <botan/types.h>
 #include <botan/xmss_publickey.h>
 #include <botan/xmss_common_ops.h>
-#include <botan/internal/pk_ops.h>
+#include <botan/pk_ops.h>
 #include <botan/internal/xmss_signature.h>
 
 namespace Botan {
diff --git a/src/lib/pubkey/xmss/xmss_wots_signature_operation.h b/src/lib/pubkey/xmss/xmss_wots_signature_operation.h
index 69ba6b4fe..59de4ea34 100644
--- a/src/lib/pubkey/xmss/xmss_wots_signature_operation.h
+++ b/src/lib/pubkey/xmss/xmss_wots_signature_operation.h
@@ -12,7 +12,7 @@
 #include <iterator>
 #include <botan/assert.h>
 #include <botan/types.h>
-#include <botan/internal/pk_ops.h>
+#include <botan/pk_ops.h>
 #include <botan/internal/xmss_wots_addressed_privatekey.h>
 #include <botan/internal/xmss_wots_common_ops.h>
 
diff --git a/src/lib/pubkey/xmss/xmss_wots_verification_operation.h b/src/lib/pubkey/xmss/xmss_wots_verification_operation.h
index 1125a6af8..a0cb0709f 100644
--- a/src/lib/pubkey/xmss/xmss_wots_verification_operation.h
+++ b/src/lib/pubkey/xmss/xmss_wots_verification_operation.h
@@ -11,7 +11,7 @@
 #include <cstddef>
 #include <iterator>
 #include <botan/types.h>
-#include <botan/internal/pk_ops.h>
+#include <botan/pk_ops.h>
 #include <botan/internal/xmss_wots_addressed_publickey.h>
 #include <botan/internal/xmss_wots_common_ops.h>