diff --git a/PInvoke/WinTrust/MsCat.cs b/PInvoke/WinTrust/MsCat.cs index 5dea6ee3..352b0f5c 100644 --- a/PInvoke/WinTrust/MsCat.cs +++ b/PInvoke/WinTrust/MsCat.cs @@ -1,5 +1,6 @@ using System; using System.Runtime.InteropServices; +using Vanara.Extensions; using static Vanara.PInvoke.Crypt32; namespace Vanara.PInvoke @@ -156,11 +157,20 @@ namespace Vanara.PInvoke CRYPTCAT_E_CDF_ATTR_TYPECOMBO = 0x00020004, } - /// Flags used by CRYPTCATSTORE. - [PInvokeData("mscat.h", MSDNShortId = "65a15797-453c-4f47-8ea1-c92e616b50aa")] + /// Flags used by and . + [PInvokeData("mscat.h", MSDNShortId = "e81f3a3d-d5b7-4266-838d-b83e331c8594")] [Flags] public enum CRYPTCAT_OPEN : uint { + /// Opens the file, if it exists, or creates a new file, if needed. + CRYPTCAT_OPEN_ALWAYS = 0x00000002, + + /// A new catalog file is created. If a previously created file exists, it is overwritten. + CRYPTCAT_OPEN_CREATENEW = 0x00000001, + + /// Opens the file, only if it exists. + CRYPTCAT_OPEN_EXISTING = 0x00000004, + /// Exclude page hashes in SPC_INDIRECT_DATA. CRYPTCAT_OPEN_EXCLUDE_PAGE_HASHES = 0x00010000, @@ -182,6 +192,20 @@ namespace Vanara.PInvoke CRYPTCAT_OPEN_VERIFYSIGHASH = 0x10000000, } + /// Version values used by . + [PInvokeData("mscat.h", MSDNShortId = "e81f3a3d-d5b7-4266-838d-b83e331c8594")] + public enum CRYPTCAT_VERSION + { + /// Version 1 file format. + CRYPTCAT_VERSION_1 = 0x100, + + /// + /// Version 2 file format. + /// Windows 8 and Windows Server 2012: Support for this value begins. + /// + CRYPTCAT_VERSION_2 = 0x200, + } + /// /// /// [The CryptCATAdminAcquireContext function is available for use in the operating systems specified in the Requirements @@ -591,6 +615,775 @@ namespace Vanara.PInvoke [return: MarshalAs(UnmanagedType.Bool)] public static extern bool CryptCATAdminReleaseContext([In] HCATADMIN hCatAdmin, [In] uint dwFlags = 0); + /// + /// + /// [The CryptCATAdminRemoveCatalog function is available for use in the operating systems specified in the Requirements + /// section. It may be altered or unavailable in subsequent versions.] + /// + /// + /// The CryptCATAdminRemoveCatalog function deletes a catalog file and removes that catalog's entry from the Windows catalog + /// database. This function is the only supported way to remove catalogs from the database while ensuring the integrity of the + /// database. The function has no associated import library. You must use the LoadLibrary and GetProcAddress functions to + /// dynamically link to Wintrust.dll. + /// + /// + /// Handle previously assigned by the CryptCATAdminAcquireContext function. + /// + /// A pointer to a null-terminated string for the name of the catalog to remove. This string must contain only the name, without any + /// path information. + /// + /// This parameter is reserved for future use and must be set to zero. + /// + /// The return value is TRUE if the function succeeds; FALSE if the function fails. + /// + /// For extended error information, call the GetLastError function. For a complete list of error codes provided by the operating + /// system, see System Error Codes. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/mscat/nf-mscat-cryptcatadminremovecatalog BOOL CryptCATAdminRemoveCatalog( IN + // HCATADMIN hCatAdmin, IN LPCWSTR pwszCatalogFile, IN DWORD dwFlags ); + [DllImport(Lib.Wintrust, SetLastError = true, ExactSpelling = true)] + [PInvokeData("mscat.h", MSDNShortId = "e09fe991-0e7a-45da-910a-8cb148bdff9a")] + [return: MarshalAs(UnmanagedType.Bool)] + public static extern bool CryptCATAdminRemoveCatalog(HCATADMIN hCatAdmin, [MarshalAs(UnmanagedType.LPWStr)] string pwszCatalogFile, uint dwFlags = 0); + + /// + /// + /// [The CryptCATAdminResolveCatalogPath function is available for use in the operating systems specified in the Requirements + /// section. It may be altered or unavailable in subsequent versions.] + /// + /// The CryptCATAdminResolveCatalogPath function retrieves the fully qualified path of the specified catalog. + /// + /// Note This function has no associated import library. You must use the LoadLibrary and GetProcAddress functions to + /// dynamically link to Wintrust.dll. + /// + /// + /// A handle that was previously assigned by the CryptCATAdminAcquireContext function. + /// The name of the catalog file for which to retrieve the fully qualified path. + /// + /// A pointer to the CATALOG_INFO structure. This value cannot be NULL. Upon return from this function, the wszCatalogFile + /// member of the CATALOG_INFO structure contains the catalog file name. + /// + /// This parameter is reserved and must be set to zero. + /// + /// Returns nonzero if successful or zero otherwise. + /// + /// For extended error information, call the GetLastError function. For a complete list of error codes provided by the operating + /// system, see System Error Codes. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/mscat/nf-mscat-cryptcatadminresolvecatalogpath BOOL + // CryptCATAdminResolveCatalogPath( HCATADMIN hCatAdmin, WCHAR *pwszCatalogFile, CATALOG_INFO *psCatInfo, DWORD dwFlags ); + [DllImport(Lib.Wintrust, SetLastError = true, ExactSpelling = true)] + [PInvokeData("mscat.h", MSDNShortId = "bdbfa02d-8801-40d4-84f4-bc5a449bce50")] + [return: MarshalAs(UnmanagedType.Bool)] + public static extern bool CryptCATAdminResolveCatalogPath(HCATADMIN hCatAdmin, [MarshalAs(UnmanagedType.LPWStr)] string pwszCatalogFile, ref CATALOG_INFO psCatInfo, uint dwFlags = 0); + + /// + /// + /// [The CryptCATCatalogInfoFromContext function is available for use in the operating systems specified in the Requirements + /// section. It may be altered or unavailable in subsequent versions.] + /// + /// + /// The CryptCATCatalogInfoFromContext function retrieves catalog information from a specified catalog context. This function + /// has no associated import library. You must use the LoadLibrary and GetProcAddress functions to dynamically link to Wintrust.dll. + /// + /// + /// A handle to the catalog context. This value cannot be NULL. + /// + /// A pointer to the CATALOG_INFO structure. This value cannot be NULL. Upon return from this function, the wszCatalogFile + /// member of the CATALOG_INFO structure contains the catalog file name. + /// + /// Unused; set to zero. + /// + /// The return value is TRUE if the function succeeds; FALSE if the function fails. + /// + /// For extended error information, call the GetLastError function. For a complete list of error codes provided by the operating + /// system, see System Error Codes. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/mscat/nf-mscat-cryptcatcataloginfofromcontext BOOL + // CryptCATCatalogInfoFromContext( HCATINFO hCatInfo, CATALOG_INFO *psCatInfo, DWORD dwFlags ); + [DllImport(Lib.Wintrust, SetLastError = true, ExactSpelling = true)] + [PInvokeData("mscat.h", MSDNShortId = "ec195fcc-1cff-4dd6-9075-c4904b653da7")] + [return: MarshalAs(UnmanagedType.Bool)] + public static extern bool CryptCATCatalogInfoFromContext(HCATINFO hCatInfo, ref CATALOG_INFO psCatInfo, uint dwFlags = 0); + + /// + /// + /// [The CryptCATCDFClose function is available for use in the operating systems specified in the Requirements section. It + /// may be altered or unavailable in subsequent versions.] + /// + /// + /// The CryptCATCDFClose function closes a catalog definition file (CDF) and frees the memory for the corresponding + /// CRYPTCATCDF structure. CryptCATCDFClose is called by MakeCat. + /// + /// + /// A pointer to a CRYPTCATCDF structure. + /// + /// Upon success, this function returns TRUE. The CryptCATCDFClose function returns FALSE with an + /// ERROR_INVALID_PARAMETER error if it fails. + /// + /// + /// Before closing the catalog output file specified in pCDF, the CryptCATCDFClose function signs and persists it to the file system. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/mscat/nf-mscat-cryptcatcdfclose BOOL CryptCATCDFClose( IN CRYPTCATCDF *pCDF ); + [DllImport(Lib.Wintrust, SetLastError = false, ExactSpelling = true)] + [PInvokeData("mscat.h", MSDNShortId = "9f2a1175-f9fe-4f4d-bf6f-e4f4c59739ec")] + [return: MarshalAs(UnmanagedType.Bool)] + public static extern bool CryptCATCDFClose(IntPtr pCDF); + + /// + /// + /// [The CryptCATCDFEnumCatAttributes function is available for use in the operating systems specified in the Requirements + /// section. It may be altered or unavailable in subsequent versions.] + /// + /// + /// The CryptCATCDFEnumCatAttributes function enumerates catalog-level attributes within the CatalogHeader section of + /// a catalog definition file (CDF). CryptCATCDFEnumCatAttributes is called by MakeCat. + /// + /// + /// A pointer to a CRYPTCATCDF structure. + /// A pointer to a CRYPTCATATTRIBUTE structure for a catalog attribute in the CDF pointed to by pCDF. + /// A pointer to a user-defined function to handle file parse errors. + /// + /// Upon success, this function returns a pointer to a CRYPTCATATTRIBUTE structure. The CryptCATCDFEnumCatAttributes function + /// returns a NULL pointer if it fails. + /// + /// + /// + /// You typically call this function in a loop to enumerate all of the catalog header attributes in a CDF. Before entering the loop, + /// set pPrevAttr to NULL. The function returns a pointer to the first attribute. Set pPrevAttr to the return value of the + /// function for subsequent iterations of the loop. + /// + /// Examples + /// The following example shows the correct sequence of assignments for the pPrevAttr parameter (). + /// + // https://docs.microsoft.com/en-us/windows/win32/api/mscat/nf-mscat-cryptcatcdfenumcatattributes CRYPTCATATTRIBUTE * + // CryptCATCDFEnumCatAttributes( CRYPTCATCDF *pCDF, CRYPTCATATTRIBUTE *pPrevAttr, PFN_CDF_PARSE_ERROR_CALLBACK pfnParseError ); + [DllImport(Lib.Wintrust, SetLastError = false, ExactSpelling = true)] + [PInvokeData("mscat.h", MSDNShortId = "01889cb9-7bf4-4591-9bb2-b263c4effe0c")] + public static extern IntPtr CryptCATCDFEnumCatAttributes(SafeCRYPTCATCDF pCDF, IntPtr pPrevAttr, PfnCdfParseErrorCallback pfnParseError); + + /// + /// + /// [The CryptCATCDFOpen function is available for use in the operating systems specified in the Requirements section. It may + /// be altered or unavailable in subsequent versions.] + /// + /// + /// The CryptCATCDFOpen function opens an existing catalog definition file (CDF) for reading and initializes a CRYPTCATCDF + /// structure. CryptCATCDFOpen is called by MakeCat. + /// + /// + /// A pointer to a null-terminated string that contains the path of the CDF file to open. + /// A pointer to a user-defined function to handle file parse errors. + /// + /// Upon success, this function returns a pointer to the newly created CRYPTCATCDF structure. The CryptCATCDFOpen function + /// returns a NULL pointer if it fails. + /// + /// + /// + /// The following default values are used by the CryptCATCDFOpen function for given conditions in the CDF + /// CatalogHeader section. + /// + /// + /// + /// CatalogHeader condition + /// Default value + /// + /// + /// No Name value is specified. + /// The file name in pwszFilePath is used for the catalog (.cat) output file. + /// + /// + /// No PublicVersion value is specified. + /// 0x00000001 + /// + /// + /// No EncodingType value is specified. + /// PKCS_7_ASN_ENCODING or X509_ASN_ENCODING (0x00010001) + /// + /// + /// The following actions are performed by the CryptCATCDFOpen function for given error conditions. + /// + /// + /// Error condition + /// Action performed + /// + /// + /// No CatalogHeader or Name tags are found in CDF. + /// + /// If specified by the caller, the CryptCATCDFOpen function calls the function specified by pfnParseError and returns a NULL pointer. + /// + /// + /// + /// + /// The CryptCATCDFOpen function calls the CryptCATOpen function to get a handle to the catalog (.cat) output file, but it gets an + /// invalid or NULL handle. + /// + /// Calls the CryptCATCDFClose function and returns a NULL pointer. + /// + /// + /// + /// + /// Additional OIDs for the Catalog branch + /// Definition + /// + /// + /// szOID_CATALOG_LIST_MEMBER_V2 + /// 1.3.6.1.4.1.311.12.1.3 + /// + /// + /// CAT_MEMBERINFO2_OBJID + /// 1.3.6.1.4.1.311.12.2.3 + /// + /// + /// + /// Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP: The additional + /// Catalog OIDs are not available. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/mscat/nf-mscat-cryptcatcdfopen CRYPTCATCDF * CryptCATCDFOpen( LPWSTR + // pwszFilePath, PFN_CDF_PARSE_ERROR_CALLBACK pfnParseError ); + [DllImport(Lib.Wintrust, SetLastError = false, ExactSpelling = true)] + [PInvokeData("mscat.h", MSDNShortId = "d400d8bd-c0a0-41dc-9093-8e4fc758d82f")] + public static extern SafeCRYPTCATCDF CryptCATCDFOpen([MarshalAs(UnmanagedType.LPWStr)] string pwszFilePath, PfnCdfParseErrorCallback pfnParseError); + + /// + /// + /// [The CryptCATClose function is available for use in the operating systems specified in the Requirements section. It may + /// be altered or unavailable in subsequent versions.] + /// + /// + /// The CryptCATClose function closes a catalog handle opened previously by the CryptCATOpen function. This function has no + /// associated import library. You must use the LoadLibrary and GetProcAddress functions to dynamically link to Wintrust.dll. + /// + /// + /// Handle opened previously by a call to the CryptCATOpen function. + /// The return value is TRUE if the function succeeds; FALSE if the function fails. + // https://docs.microsoft.com/en-us/windows/win32/api/mscat/nf-mscat-cryptcatclose BOOL CryptCATClose( IN HANDLE hCatalog ); + [DllImport(Lib.Wintrust, SetLastError = false, ExactSpelling = true)] + [PInvokeData("mscat.h", MSDNShortId = "f6fa2d10-0049-4d5e-9688-566e5c11d64e")] + [return: MarshalAs(UnmanagedType.Bool)] + public static extern bool CryptCATClose(HCATALOG hCatalog); + + /// + /// + /// [The CryptCATEnumerateAttr function is available for use in the operating systems specified in the Requirements section. + /// It may be altered or unavailable in subsequent versions.] + /// + /// + /// The CryptCATEnumerateAttr function enumerates the attributes associated with a member of a catalog. This function has no + /// associated import library. You must use the LoadLibrary and GetProcAddress functions to dynamically link to Wintrust.dll. + /// + /// + /// Handle for the catalog that contains the member identified by pCatMember. This value cannot be NULL. + /// A pointer to the CRYPTCATMEMBER structure that identifies which member of the catalog is being enumerated. + /// + /// A pointer to the previously returned value from this function or pointer to NULL to start the enumeration. + /// + /// + /// The return value is a pointer to the CRYPTCATATTRIBUTE structure that contains the attribute information or NULL, if no + /// more attributes are in the enumeration or if an error is encountered. The returned pointer is passed in as the pPrevAttr + /// parameter for subsequent calls to this function. + /// + /// Do not free the returned pointer nor any of the members pointed to by the returned pointer. + // https://docs.microsoft.com/en-us/windows/win32/api/mscat/nf-mscat-cryptcatenumerateattr CRYPTCATATTRIBUTE * + // CryptCATEnumerateAttr( IN HANDLE hCatalog, IN CRYPTCATMEMBER *pCatMember, IN CRYPTCATATTRIBUTE *pPrevAttr ); + [DllImport(Lib.Wintrust, SetLastError = false, ExactSpelling = true)] + [PInvokeData("mscat.h", MSDNShortId = "064e87db-4330-4b8b-9865-ba8b9714f6e4")] + public static extern IntPtr CryptCATEnumerateAttr(HCATALOG hCatalog, in CRYPTCATMEMBER pCatMember, IntPtr pPrevAttr); + + /// + /// + /// [The CryptCATEnumerateCatAttr function is available for use in the operating systems specified in the Requirements + /// section. It may be altered or unavailable in subsequent versions.] + /// + /// + /// The CryptCATEnumerateCatAttr function enumerates the attributes associated with a catalog. This function has no + /// associated import library. You must use the LoadLibrary and GetProcAddress functions to dynamically link to Wintrust.dll. + /// + /// + /// Handle for the catalog whose attributes are being enumerated. This value cannot be NULL. + /// + /// A pointer to the previously returned pointer to the CRYPTCATATTRIBUTE structure from this function or pointer to NULL to + /// start the enumeration. + /// + /// + /// The return value is a pointer to the CRYPTCATATTRIBUTE structure that contains the attribute information or NULL, if no + /// more attributes are in the enumeration or if an error is encountered. The returned pointer is passed in as the pPrevAttr + /// parameter for subsequent calls to this function. + /// + /// Do not free the returned pointer nor any of the members pointed to by the returned pointer. + // https://docs.microsoft.com/en-us/windows/win32/api/mscat/nf-mscat-cryptcatenumeratecatattr CRYPTCATATTRIBUTE * + // CryptCATEnumerateCatAttr( IN HANDLE hCatalog, IN CRYPTCATATTRIBUTE *pPrevAttr ); + [DllImport(Lib.Wintrust, SetLastError = false, ExactSpelling = true)] + [PInvokeData("mscat.h", MSDNShortId = "57b6ff5c-e47e-41ac-8ec8-01a47ea77acf")] + public static extern IntPtr CryptCATEnumerateCatAttr(HCATALOG hCatalog, IntPtr pPrevAttr); + + /// + /// + /// [The CryptCATEnumerateMember function is available for use in the operating systems specified in the Requirements + /// section. It may be altered or unavailable in subsequent versions.] + /// + /// The CryptCATEnumerateMember function enumerates the members of a catalog. + /// + /// The handle of the catalog that contains the members to enumerate. This value cannot be NULL. + /// + /// A pointer to a CRYPTCATMEMBER structure that identifies which member of the catalog was last retrieved. If this parameter is + /// NULL, this function will retrieve the first member of the catalog. + /// + /// + /// This function returns a pointer to a CRYPTCATMEMBER structure that represents the next member of the catalog. If there are no + /// more members in the catalog to enumerate, this function returns NULL. + /// + /// + /// Do not free the returned pointer nor any of the members pointed to by the returned pointer. + /// Examples + /// The following pseudocode example shows how to use this function to enumerate all of the members of a catalog. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/mscat/nf-mscat-cryptcatenumeratemember CRYPTCATMEMBER * + // CryptCATEnumerateMember( IN HANDLE hCatalog, IN CRYPTCATMEMBER *pPrevMember ); + [DllImport(Lib.Wintrust, SetLastError = false, ExactSpelling = true)] + [PInvokeData("mscat.h", MSDNShortId = "6bbfef11-a150-4255-8620-27c1b1587b48")] + public static extern IntPtr CryptCATEnumerateMember(HCATALOG hCatalog, IntPtr pPrevMember); + + /// + /// + /// [The CryptCATGetAttrInfo function is available for use in the operating systems specified in the Requirements section. It + /// may be altered or unavailable in subsequent versions.] + /// + /// The CryptCATGetAttrInfo function retrieves information about an attribute of a member of a catalog. + /// + /// + /// The handle of the catalog that contains the member to retrieve the attribute information for. This handle is obtained by calling + /// the CryptCATOpen function. This parameter is required and cannot be NULL. + /// + /// + /// A pointer to a CRYPTCATMEMBER structure that represents the member to retrieve the attribute information for. This can be + /// obtained by calling the CryptCATGetMemberInfo function. This parameter is required and cannot be NULL. + /// + /// + /// A pointer to a null-terminated Unicode string that contains the name of the attribute to retrieve the information for. This + /// parameter is required and cannot be NULL. + /// + /// + /// + /// This function returns a pointer to a CRYPTCATATTRIBUTE structure that contains the attribute information. If the function fails, + /// it returns NULL. + /// + /// Important Do not free the returned pointer nor any of the members pointed to by the returned pointer. + /// + /// If this function returns NULL, additional error information can be obtained by calling the GetLastError function. + /// GetLastError will return one of the following error codes. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// CRYPT_E_NOT_FOUND + /// The member or the attribute could not be found. + /// + /// + /// ERROR_INVALID_PARAMETER + /// One or more of the parameters are not valid. + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/mscat/nf-mscat-cryptcatgetattrinfo CRYPTCATATTRIBUTE * CryptCATGetAttrInfo( IN + // HANDLE hCatalog, IN CRYPTCATMEMBER *pCatMember, LPWSTR pwszReferenceTag ); + [DllImport(Lib.Wintrust, SetLastError = true, ExactSpelling = true)] + [PInvokeData("mscat.h", MSDNShortId = "e36966ea-741e-4380-85cd-5a3c9db38e6d")] + public static extern IntPtr CryptCATGetAttrInfo(HCATALOG hCatalog, in CRYPTCATMEMBER pCatMember, [MarshalAs(UnmanagedType.LPWStr)] string pwszReferenceTag); + + /// + /// + /// [The CryptCATGetMemberInfo function is available for use in the operating systems specified in the Requirements section. + /// It may be altered or unavailable in subsequent versions.] + /// + /// + /// The CryptCATGetMemberInfo function retrieves member information from the catalog's PKCS #7. In addition to retrieving the + /// member information for a specified reference tag, this function opens a member context. This function has no associated import + /// library. You must use the LoadLibrary and GetProcAddress functions to dynamically link to Wintrust.dll. + /// + /// + /// A handle to the catalog. This parameter cannot be NULL. + /// + /// A pointer to a null-terminated string that represents the reference tag for the member information being retrieved. + /// + /// + /// A pointer to the CRYPTCATMEMBER structure that contains the member information or NULL, if no information can be found. + /// + /// Do not free the returned pointer nor any of the members pointed to by the returned pointer. + // https://docs.microsoft.com/en-us/windows/win32/api/mscat/nf-mscat-cryptcatgetmemberinfo CRYPTCATMEMBER * CryptCATGetMemberInfo( + // IN HANDLE hCatalog, LPWSTR pwszReferenceTag ); + [DllImport(Lib.Wintrust, SetLastError = false, ExactSpelling = true)] + [PInvokeData("mscat.h", MSDNShortId = "ff265232-f57e-4ab0-ba07-05e6d6745ae3")] + public static extern IntPtr CryptCATGetMemberInfo(HCATALOG hCatalog, [MarshalAs(UnmanagedType.LPWStr)] string pwszReferenceTag); + + /// + /// + /// [The CryptCATHandleFromStore function is available for use in the operating systems specified in the Requirements + /// section. It may be altered or unavailable in subsequent versions.] + /// + /// The CryptCATHandleFromStore function retrieves a catalog handle from memory. + /// + /// A pointer to a CRYPTCATSTORE structure that contains the handle to retrieve. + /// A handle to the catalog. + // https://docs.microsoft.com/en-us/windows/win32/api/mscat/nf-mscat-cryptcathandlefromstore HANDLE CryptCATHandleFromStore( IN + // CRYPTCATSTORE *pCatStore ); + [DllImport(Lib.Wintrust, SetLastError = false, ExactSpelling = true)] + [PInvokeData("mscat.h", MSDNShortId = "e9aedc2d-9492-4ed7-9f2d-891997f85f6f")] + public static extern SafeHCATALOG CryptCATHandleFromStore(in CRYPTCATSTORE pCatStore); + + /// + /// + /// [The CryptCATOpen function is available for use in the operating systems specified in the Requirements section. It may be + /// altered or unavailable in subsequent versions.] + /// + /// The CryptCATOpen function opens a catalog and returns a context handle to the open catalog. + /// + /// Note Some older versions of Wintrust.lib do not contain the export information for this function. In this case, you must + /// use the LoadLibrary and GetProcAddress functions to dynamically link to Wintrust.dll. + /// + /// + /// A pointer to a null-terminated string for the catalog file name. + /// + /// Zero, to open an existing catalog file, or a bitwise combination of one or more of the following values. + /// + /// + /// Value + /// Meaning + /// + /// + /// CRYPTCAT_OPEN_ALWAYS + /// Opens the file, if it exists, or creates a new file, if needed. + /// + /// + /// CRYPTCAT_OPEN_CREATENEW + /// A new catalog file is created. If a previously created file exists, it is overwritten. + /// + /// + /// + /// A handle to a cryptographic service provider (CSP). + /// + /// Version of the file. This can be one of the following values. + /// + /// + /// Value + /// Meaning + /// + /// + /// CRYPTCAT_VERSION_1 0x100 + /// Version 1 file format. + /// + /// + /// CRYPTCAT_VERSION_2 0x200 + /// Version 2 file format. Windows 8 and Windows Server 2012: Support for this value begins. + /// + /// + /// + /// + /// Encoding type used for the file. If this value is 0, then the encoding type is set to PKCS_7_ASN_ENCODING | X509_ASN_ENCODING. + /// + /// + /// Upon success, this function returns a handle to the open catalog. When you have finished using the handle, close it by calling + /// the CryptCATClose function. The CryptCATOpen function returns INVALID_HANDLE_VALUE if it fails. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/mscat/nf-mscat-cryptcatopen HANDLE CryptCATOpen( LPWSTR pwszFileName, IN DWORD + // fdwOpenFlags, IN HCRYPTPROV hProv, IN DWORD dwPublicVersion, IN DWORD dwEncodingType ); + [DllImport(Lib.Wintrust, SetLastError = false, ExactSpelling = true)] + [PInvokeData("mscat.h", MSDNShortId = "e81f3a3d-d5b7-4266-838d-b83e331c8594")] + public static extern SafeHCATALOG CryptCATOpen([MarshalAs(UnmanagedType.LPWStr)] string pwszFileName, CRYPTCAT_OPEN fdwOpenFlags, [In] HCRYPTPROV hProv, [In] CRYPTCAT_VERSION dwPublicVersion, CertEncodingType dwEncodingType); + + /// + /// + /// [The CryptCATPersistStore function is available for use in the operating systems specified in the Requirements section. + /// It may be altered or unavailable in subsequent versions.] + /// + /// The CryptCATPersistStore function saves the information in the specified catalog store to an unsigned catalog file. + /// + /// + /// A handle to the catalog obtained from CryptCATHandleFromStore or CryptCATOpen function. Beginning with Windows 8 you must use + /// only CryptCATOpen to retrieve a handle. + /// + /// + /// The return value is TRUE if the function succeeds; otherwise, FALSE. + /// + /// If this function returns FALSE, additional error information can be obtained by calling the GetLastError function. + /// GetLastError will return the following error code. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// ERROR_INVALID_PARAMETER + /// One or more of the parameters are not valid. + /// + /// + /// ERROR_NOT_SUPPORTED + /// + /// Beginning with Windows 8 and Windows Server 2012, you must retrieve a handle by calling the CryptCATOpen function with the + /// dwPublicVersion parameter set to 0x100 or 0x200. For more information, see Remarks. + /// + /// + /// + /// + /// + /// The pwszP7File member of the CRYPTCATSTORE structure must be initialized before you call CryptCATPersistStore. + /// Beginning with Windows 8 and Windows Server 2012, the following changes apply to this function: + /// + /// + /// If CryptCATOpen was called with a dwPublicVersion parameter of 0x200, the catalog is written by using the v2 format. + /// + /// + /// If CryptCATOpen was called with a dwPublicVersion parameter of 0x100, the catalog is written by using the v1 format. + /// + /// + /// + /// If CryptCATOpen was called with a dwPublicVersion parameter other than 0x200 or 0x100, the CryptCATPersistStore function + /// returns FALSE and the error code is set to ERROR_NOT_SUPPORTED. + /// + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/mscat/nf-mscat-cryptcatpersiststore BOOL CryptCATPersistStore( IN HANDLE + // hCatalog ); + [DllImport(Lib.Wintrust, SetLastError = true, ExactSpelling = true)] + [PInvokeData("mscat.h", MSDNShortId = "2a564b0e-fcc6-4702-8173-d18df7064e53")] + [return: MarshalAs(UnmanagedType.Bool)] + public static extern bool CryptCATPersistStore([In] HCATALOG hCatalog); + + /// + /// + /// [The CryptCATPutAttrInfo function is available for use in the operating systems specified in the Requirements section. It + /// may be altered or unavailable in subsequent versions.] + /// + /// The CryptCATPutAttrInfo function allocates memory for an attribute and adds it to a catalog member. + /// + /// A handle to the catalog obtained from the CryptCATOpen or CryptCATHandleFromStore function. + /// A pointer to a CRYPTCATMEMBER structure that contains the catalog member. + /// A pointer to a null-terminated string that contains the name of the attribute. + /// + /// + /// A value that represents a bitwise combination of the following flags. The caller must at least specify + /// CRYPTCAT_ATTR_DATABASE64 or CRYPTCAT_ATTR_DATAASCII. + /// + /// + /// + /// Value + /// Meaning + /// + /// + /// CRYPTCAT_ATTR_AUTHENTICATED 0x10000000 + /// The attribute is authenticated. + /// + /// + /// CRYPTCAT_ATTR_UNAUTHENTICATED 0x20000000 + /// The attribute is unauthenticated. + /// + /// + /// CRYPTCAT_ATTR_NAMEASCII 0x00000001 + /// The attribute is an ASCII string. + /// + /// + /// CRYPTCAT_ATTR_NAMEOBJID 0x00000002 + /// The attribute is a cryptographic object identifier (OID). + /// + /// + /// CRYPTCAT_ATTR_DATAASCII 0x00010000 + /// The attribute contains simple ASCII characters that should not be decoded. + /// + /// + /// CRYPTCAT_ATTR_DATABASE64 0x00020000 + /// The attribute is in base 64 format. + /// + /// + /// CRYPTCAT_ATTR_DATAREPLACE 0x00040000 + /// The attribute replaces the value for an existing attribute. + /// + /// + /// + /// A value that specifies the number of bytes in the pbData buffer. + /// A pointer to a memory buffer that contains the attribute value. + /// + /// + /// Upon success, this function returns a pointer to a CRYPTCATATTRIBUTE structure that contains the assigned attribute. The caller + /// must not free this pointer or any of its members. + /// + /// + /// If this function returns NULL, additional error information can be obtained by calling the GetLastError function. + /// GetLastError will return one of the following error codes. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// ERROR_INVALID_PARAMETER + /// One or more of the parameters are not valid. + /// + /// + /// ERROR_NOT_ENOUGH_MEMORY + /// The operating system ran out of memory during the operation. + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/mscat/nf-mscat-cryptcatputattrinfo CRYPTCATATTRIBUTE * CryptCATPutAttrInfo( IN + // HANDLE hCatalog, IN CRYPTCATMEMBER *pCatMember, LPWSTR pwszReferenceTag, IN DWORD dwAttrTypeAndAction, IN DWORD cbData, IN BYTE + // *pbData ); + [DllImport(Lib.Wintrust, SetLastError = true, ExactSpelling = true)] + [PInvokeData("mscat.h", MSDNShortId = "13d5cdb4-2a15-4442-9e11-c3f76ca03f7e")] + public static extern IntPtr CryptCATPutAttrInfo([In] HCATALOG hCatalog, in CRYPTCATMEMBER pCatMember, [MarshalAs(UnmanagedType.LPWStr)] string pwszReferenceTag, [In] CRYPTCAT_ATTR dwAttrTypeAndAction, [In] uint cbData, [In] IntPtr pbData); + + /// + /// + /// [The CryptCATPutCatAttrInfo function is available for use in the operating systems specified in the Requirements section. + /// It may be altered or unavailable in subsequent versions.] + /// + /// The CryptCATPutCatAttrInfo function allocates memory for a catalog file attribute and adds it to the catalog. + /// + /// A handle to the catalog obtained from the CryptCATOpen or CryptCATHandleFromStore functions. + /// A pointer to a null-terminated string for the name of the attribute. + /// + /// + /// A value that represents a bitwise combination of the following flags. The caller must at least specify + /// CRYPTCAT_ATTR_DATAASCII or CRYPTCAT_ATTR_DATABASE64. + /// + /// + /// + /// Value + /// Meaning + /// + /// + /// CRYPTCAT_ATTR_AUTHENTICATED 0x10000000 + /// The attribute is authenticated. + /// + /// + /// CRYPTCAT_ATTR_UNAUTHENTICATED 0x20000000 + /// The attribute is unauthenticated. + /// + /// + /// CRYPTCAT_ATTR_NAMEASCII 0x00000001 + /// The attribute is an ASCII string. + /// + /// + /// CRYPTCAT_ATTR_NAMEOBJID 0x00000002 + /// The attribute is a cryptographic object identifier (OID). + /// + /// + /// CRYPTCAT_ATTR_DATAASCII 0x00010000 + /// The attribute contains simple ASCII characters that should not be decoded. + /// + /// + /// CRYPTCAT_ATTR_DATABASE64 0x00020000 + /// The attribute is in base 64 format. + /// + /// + /// CRYPTCAT_ATTR_DATAREPLACE 0x00040000 + /// The attribute replaces the value for an existing attribute. + /// + /// + /// + /// A value that specifies the number of bytes in the pbData buffer. + /// A pointer to a memory buffer that contains the attribute value. + /// + /// + /// A pointer to a CRYPTCATATTRIBUTE structure that contains the catalog attribute. The caller must not free this pointer or any of + /// its members. + /// + /// + /// If this function returns NULL, additional error information can be obtained by calling the GetLastError function. + /// GetLastError will return one of the following error codes. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// ERROR_INVALID_PARAMETER + /// One or more of the parameters are not valid. + /// + /// + /// ERROR_NOT_ENOUGH_MEMORY + /// The operating system ran out of memory during the operation. + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/mscat/nf-mscat-cryptcatputcatattrinfo CRYPTCATATTRIBUTE * + // CryptCATPutCatAttrInfo( IN HANDLE hCatalog, LPWSTR pwszReferenceTag, IN DWORD dwAttrTypeAndAction, IN DWORD cbData, IN BYTE + // *pbData ); + [DllImport(Lib.Wintrust, SetLastError = true, ExactSpelling = true)] + [PInvokeData("mscat.h", MSDNShortId = "16bb8560-d4fc-4c81-8eed-21a2da7f396d")] + public static extern IntPtr CryptCATPutCatAttrInfo(HCATALOG hCatalog, [MarshalAs(UnmanagedType.LPWStr)] string pwszReferenceTag, [In] CRYPTCAT_ATTR dwAttrTypeAndAction, [In] uint cbData, [In] IntPtr pbData); + + /// + /// + /// [The CryptCATPutMemberInfo function is available for use in the operating systems specified in the Requirements section. + /// It may be altered or unavailable in subsequent versions.] + /// + /// The CryptCATPutMemberInfo function allocates memory for a catalog member and adds it to the catalog. + /// + /// A handle to the catalog obtained from the CryptCATOpen or CryptCATHandleFromStore function. + /// A pointer to a null-terminated string for the catalog file name. + /// A pointer to a null-terminated string that contains the name of the member. + /// A GUID for the subject type of the member. + /// A value that specifies the certificate version. + /// A value that specifies the number of bytes in the pbSIPIndirectData buffer. + /// A pointer to a memory buffer for subject interface package (SIP)-indirect data. + /// + /// + /// A pointer to a CRYPTCATMEMBER structure that contains the assigned member. The caller must not free this pointer or any of its members. + /// + /// + /// If this function returns NULL, additional error information can be obtained by calling the GetLastError function. + /// GetLastError will return one of the following error codes. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// ERROR_INVALID_PARAMETER + /// One or more of the parameters are not valid. + /// + /// + /// ERROR_NOT_ENOUGH_MEMORY + /// The operating system ran out of memory during the operation. + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/mscat/nf-mscat-cryptcatputmemberinfo CRYPTCATMEMBER * CryptCATPutMemberInfo( + // IN HANDLE hCatalog, LPWSTR pwszFileName, LPWSTR pwszReferenceTag, IN GUID *pgSubjectType, IN DWORD dwCertVersion, IN DWORD + // cbSIPIndirectData, IN BYTE *pbSIPIndirectData ); + [DllImport(Lib.Wintrust, SetLastError = true, ExactSpelling = true)] + [PInvokeData("mscat.h", MSDNShortId = "bfc10577-e32e-4b2e-ad24-1d0a85c6730a")] + public static extern IntPtr CryptCATPutMemberInfo([In] HCATALOG hCatalog, [MarshalAs(UnmanagedType.LPWStr)] string pwszFileName, [MarshalAs(UnmanagedType.LPWStr)] string pwszReferenceTag, in Guid pgSubjectType, [In] uint dwCertVersion, [In] uint cbSIPIndirectData, [In] IntPtr pbSIPIndirectData); + + /// + /// + /// [The CryptCATStoreFromHandle function is available for use in the operating systems specified in the Requirements + /// section. It may be altered or unavailable in subsequent versions.] + /// + /// The CryptCATStoreFromHandle function retrieves a CRYPTCATSTORE structure from a catalog handle. + /// + /// A handle to the catalog obtained from the CryptCATOpen or CryptCATHandleFromStore function. + /// + /// A pointer to a CRYPTCATSTORE structure that contains the catalog store. The caller must not free this pointer or any of its members. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/mscat/nf-mscat-cryptcatstorefromhandle CRYPTCATSTORE * + // CryptCATStoreFromHandle( IN HANDLE hCatalog ); + [DllImport(Lib.Wintrust, SetLastError = false, ExactSpelling = true)] + [PInvokeData("mscat.h", MSDNShortId = "ce4fe972-0ed5-4b18-8ec5-9883af326335")] + public static extern IntPtr CryptCATStoreFromHandle([In] HCATALOG hCatalog); + /// /// /// [The IsCatalogFile function is available for use in the operating systems specified in the Requirements section. It may @@ -913,6 +1706,54 @@ namespace Vanara.PInvoke public HANDLE hSorted; } + /// Provides a handle to a catalog. + [StructLayout(LayoutKind.Sequential)] + public struct HCATALOG : IHandle + { + private IntPtr handle; + + /// Initializes a new instance of the struct. + /// An object that represents the pre-existing handle to use. + public HCATALOG(IntPtr preexistingHandle) => handle = preexistingHandle; + + /// Returns an invalid handle by instantiating a object with . + public static HCATALOG NULL => new HCATALOG(IntPtr.Zero); + + /// Gets a value indicating whether this instance is a null handle. + public bool IsNull => handle == IntPtr.Zero; + + /// Performs an explicit conversion from to . + /// The handle. + /// The result of the conversion. + public static explicit operator IntPtr(HCATALOG h) => h.handle; + + /// Performs an implicit conversion from to . + /// The pointer to a handle. + /// The result of the conversion. + public static implicit operator HCATALOG(IntPtr h) => new HCATALOG(h); + + /// Implements the operator !=. + /// The first handle. + /// The second handle. + /// The result of the operator. + public static bool operator !=(HCATALOG h1, HCATALOG h2) => !(h1 == h2); + + /// Implements the operator ==. + /// The first handle. + /// The second handle. + /// The result of the operator. + public static bool operator ==(HCATALOG h1, HCATALOG h2) => h1.Equals(h2); + + /// + public override bool Equals(object obj) => obj is HCATALOG h ? handle == h.handle : false; + + /// + public override int GetHashCode() => handle.GetHashCode(); + + /// + public IntPtr DangerousGetHandle() => handle; + } + /// Provides a handle to a catalog information context. [StructLayout(LayoutKind.Sequential)] public struct HCATINFO : IHandle @@ -961,6 +1802,33 @@ namespace Vanara.PInvoke public IntPtr DangerousGetHandle() => handle; } + /// Provides a for that is disposed using . + public class SafeCRYPTCATCDF : SafeHANDLE + { + /// Initializes a new instance of the class and assigns an existing handle. + /// An object that represents the pre-existing handle to use. + /// + /// to reliably release the handle during the finalization phase; otherwise, (not recommended). + /// + public SafeCRYPTCATCDF(IntPtr preexistingHandle, bool ownsHandle = true) : base(preexistingHandle, ownsHandle) { } + + /// Initializes a new instance of the class. + private SafeCRYPTCATCDF() : base() { } + + /// + /// Gets the structure with the data behind this handle. If the handle is invalid, this value is the default for the structure. + /// + public CRYPTCATCDF Value => IsInvalid ? default : handle.ToStructure(); + + /// Performs an implicit conversion from to . + /// The safe handle instance. + /// The result of the conversion. + public static implicit operator CRYPTCATCDF(SafeCRYPTCATCDF h) => h.Value; + + /// + protected override bool InternalReleaseHandle() => CryptCATCDFClose(handle); + } + /// Provides a for that is disposed using . public class SafeHCATADMIN : SafeHANDLE { @@ -983,6 +1851,28 @@ namespace Vanara.PInvoke protected override bool InternalReleaseHandle() => CryptCATAdminReleaseContext(handle); } + /// Provides a for that is disposed using . + public class SafeHCATALOG : SafeHANDLE + { + /// Initializes a new instance of the class and assigns an existing handle. + /// An object that represents the pre-existing handle to use. + /// + /// to reliably release the handle during the finalization phase; otherwise, (not recommended). + /// + public SafeHCATALOG(IntPtr preexistingHandle, bool ownsHandle = true) : base(preexistingHandle, ownsHandle) { } + + /// Initializes a new instance of the class. + private SafeHCATALOG() : base() { } + + /// Performs an implicit conversion from to . + /// The safe handle instance. + /// The result of the conversion. + public static implicit operator HCATALOG(SafeHCATALOG h) => h.handle; + + /// + protected override bool InternalReleaseHandle() => CryptCATClose(handle); + } + /// Provides a for that is disposed using . public class SafeHCATINFO : SafeHANDLE { @@ -1007,27 +1897,5 @@ namespace Vanara.PInvoke /// protected override bool InternalReleaseHandle() => CryptCATAdminReleaseCatalogContext(hAdmin, handle); } - - /* - CryptCATAdminRemoveCatalog Deletes a catalog file and removes that catalog's entry from the Windows catalog database. - CryptCATAdminResolveCatalogPath Retrieves the fully qualified path of the specified catalog. - CryptCATCatalogInfoFromContext Retrieves catalog information from a specified catalog context. - CryptCATCDFClose Closes a catalog definition file (CDF) and frees the memory for the corresponding CRYPTCATCDF structure. - CryptCATCDFEnumCatAttributes Enumerates catalog-level attributes within the CatalogHeader section of a catalog definition file (CDF). - CryptCATCDFOpen Opens an existing catalog definition file (CDF) for reading and initializes a CRYPTCATCDF structure. - CryptCATClose Closes a catalog handle opened previously by the CryptCATOpen function. - CryptCATEnumerateAttr Enumerates the attributes associated with a member of a catalog. This function has no associated import library. - CryptCATEnumerateCatAttr Enumerates the attributes associated with a catalog. This function has no associated import library. - CryptCATEnumerateMember Enumerates the members of a catalog. - CryptCATGetAttrInfo Retrieves information about an attribute of a member of a catalog. - CryptCATGetMemberInfo Retrieves member information from the catalog's PKCS #7. - CryptCATHandleFromStore Retrieves a catalog handle from memory. - CryptCATOpen Opens a catalog and returns a context handle to the open catalog. - CryptCATPersistStore Saves the information in the specified catalog store to an unsigned catalog file. - CryptCATPutAttrInfo Allocates memory for an attribute and adds it to a catalog member. - CryptCATPutCatAttrInfo Allocates memory for a catalog file attribute and adds it to the catalog. - CryptCATPutMemberInfo Allocates memory for a catalog member and adds it to the catalog. - CryptCATStoreFromHandle Retrieves a CRYPTCATSTORE structure from a catalog handle. - */ } } \ No newline at end of file diff --git a/PInvoke/WinTrust/Vanara.PInvoke.WinTrust.csproj b/PInvoke/WinTrust/Vanara.PInvoke.WinTrust.csproj index 5816a2af..259d0249 100644 --- a/PInvoke/WinTrust/Vanara.PInvoke.WinTrust.csproj +++ b/PInvoke/WinTrust/Vanara.PInvoke.WinTrust.csproj @@ -4,7 +4,7 @@ wintrust.dll - PInvoke API (methods, structures and constants imported from Windows WinTrust.dll. + PInvoke API (methods, structures and constants) imported from Windows WinTrust.dll. Copyright © 2017-2019 $(AssemblyName) 3.1.2 @@ -18,7 +18,7 @@ Vanara64x64.png https://github.com/dahall/vanara Git - pinvoke;vanara;net-extensions;interop + pinvoke;vanara;net-extensions;interop;wintrust en-US true true