Expose pk_ops.h as public interface again

I was initially thinking of Botan as somewhat closed system, but
@cordney has a legit use case of wanting to expose a TPM sign
operation, but using their internal TPM library and TPM key type.
This requires the API be exposed so the derivation can occur.

Add a comment in the header explaining that the header is not for
normal application use and directing them to pubkey.h

This basically reverts 2747e8e23aec43162

16 files changed, 26 insertions, 16 deletions

diff --git a/src/lib/prov/pkcs11/p11_ecdh.cpp b/src/lib/prov/pkcs11/p11_ecdh.cpp
index 474d1dac0..f2604185d 100644
--- a/src/lib/prov/pkcs11/p11_ecdh.cpp
+++ b/src/lib/prov/pkcs11/p11_ecdh.cpp
@@ -13,7 +13,7 @@
 #include <botan/internal/p11_mechanism.h>
 #include <botan/ber_dec.h>
 #include <botan/der_enc.h>
-#include <botan/internal/pk_ops.h>
+#include <botan/pk_ops.h>
 #include <botan/rng.h>
 
 namespace Botan {
diff --git a/src/lib/prov/pkcs11/p11_ecdsa.cpp b/src/lib/prov/pkcs11/p11_ecdsa.cpp
index c2ba02e0f..852366d25 100644
--- a/src/lib/prov/pkcs11/p11_ecdsa.cpp
+++ b/src/lib/prov/pkcs11/p11_ecdsa.cpp
@@ -11,7 +11,7 @@
 #if defined(BOTAN_HAS_ECDSA)
 
 #include <botan/internal/p11_mechanism.h>
-#include <botan/internal/pk_ops.h>
+#include <botan/pk_ops.h>
 #include <botan/keypair.h>
 #include <botan/rng.h>
 
diff --git a/src/lib/prov/pkcs11/p11_rsa.cpp b/src/lib/prov/pkcs11/p11_rsa.cpp
index 0312f76bf..ea0fc874b 100644
--- a/src/lib/prov/pkcs11/p11_rsa.cpp
+++ b/src/lib/prov/pkcs11/p11_rsa.cpp
@@ -11,8 +11,7 @@
 #if defined(BOTAN_HAS_RSA)
 
 #include <botan/internal/p11_mechanism.h>
-#include <botan/internal/pk_ops.h>
-#include <botan/internal/pk_ops.h>
+#include <botan/pk_ops.h>
 #include <botan/rng.h>
 #include <botan/blinding.h>
 
diff --git a/src/lib/prov/tpm/tpm.cpp b/src/lib/prov/tpm/tpm.cpp
index cb5a242eb..0c2f9353e 100644
--- a/src/lib/prov/tpm/tpm.cpp
+++ b/src/lib/prov/tpm/tpm.cpp
@@ -11,7 +11,7 @@
 #include <botan/hash_id.h>
 #include <botan/der_enc.h>
 #include <botan/workfactor.h>
-#include <botan/internal/pk_ops.h>
+#include <botan/pk_ops.h>
 #include <sstream>
 
 #include <tss/platform.h>
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>