`, ``, ``, ``, and `` elements as specified in [[XKMS2](#XKMS)]. To allow compatibility with older versions of XKMS out there, the deprecated elements ``, `` and `` will be accepted. *[New in v20.0]* Element names with a prefix, e.g. ``, are now accepted. To make life easier to import RSA key data that exists in hexadecimal format, the user can force the function to decode the data in hexadecimal format instead of base64 by adding an attribute with the value `"hexBinary"` to each of the component elements of the RSAKeyValue. For example ``` 010001 ``` The attribute name is not important. This practice is not in conformance with any existing W3C standard (that we're aware of, anyway) but is included for convenience where the user is creating the XML file by hand using hex data. ### Example (VBA core function) This example converts an XML string into an internal public key that can be used in the other public key functions in this toolkit. ``` Dim strInternalKey As String Dim strXML As String Dim nLen As Long Dim nRet As Long strXML = "" _ & "CmZ5HcaYgWjeerd0Gbt/sMABxicQJwB1FClC4ZqNjFH" _ & "QU7PjeCod5dxa9OvplGgXARSh3+Z83Jqa9V1lViC7qw==" _ & "AQAB" _ & "" nLen = RSA_FromXMLString("", 0, strXML, 0) If nLen <= 0 Then MsgBox ("Error: " & nLen) Exit Function End If strInternalKey = String(nLen, " ") nLen = RSA_FromXMLString(strInternalKey, Len(strInternalKey), strXML, 0) strInternalKey = Left(strInternalKey, nLen) Debug.Print "INTKEY=" & strInternalKey nRet = RSA_CheckKey(strInternalKey, 0) Debug.Print "RSA_CheckKey returns " & nRet ``` The second example is the same as the first except the XML data is in hexadecimal format. ``` Dim strInternalKey As String Dim strXML As String Dim nLen As Long Dim nRet As Long strXML = "" _ & "0A66791D" _ & "C6988168DE7AB77419BB7FB0C001C627102700751429" _ & "42E19A8D8C51D053B3E3782A1DE5DC5AF4EBE9946817" _ & "0114A1DFE67CDC9A9AF55D655620BBAB" _ & "010001" _ & "" nLen = RSA_FromXMLString("", 0, strXML, 0) If nLen <= 0 Then MsgBox ("Error: " & nLen) Exit Function End If strInternalKey = String(nLen, " ") nLen = RSA_FromXMLString(strInternalKey, Len(strInternalKey), strXML, 0) strInternalKey = Left(strInternalKey, nLen) Debug.Print "INTKEY=" & strInternalKey nRet = RSA_CheckKey(strInternalKey, 0) Debug.Print "RSA_CheckKey returns " & nRet ``` Both examples should produce the output (shortened here): ``` INTKEY=MEcCQApmeR3...yamvVdZVYgu6sCAwEAAQ== RSA_CheckKey returns 1 ``` ### Example (VBA wrapper function) ``` Dim strPrivateKey As String strPrivateKey = rsaReadPrivateKey("AlicePrivRSASign.p8e", "password") Debug.Print rsaToXMLString(strPrivateKey, 0) Debug.Print rsaToXMLString(strPrivateKey, PKI_XML_EXCLPRIVATE Or PKI_XML_HEXBINARY) Debug.Print rsaToXMLStringEx(strPrivateKey, "ds", PKI_XML_EXCLPRIVATE) ' Now derive internal private key string from XML Dim strXML As String Dim strKey As String strXML = rsaToXMLString(strPrivateKey) strKey = rsaFromXMLString(strXML) Debug.Print "Key length = " & RSA_KeyBits(strKey) & " bits" ``` ### See Also [RSA_ToXMLString](#RSA_ToXMLString) [[Contents](#topofpage)] [[Index](#index)] RSA_GetPrivateKeyFromPFX ------------------------------------------------------------- Extracts an encrypted private key from a PKCS-12 PKCS8ShroudedKeyBag, saving the output directly as a new file. ### VBA/VB6 Syntax `Public Declare Function RSA_GetPrivateKeyFromPFX Lib "diCrPKI.dll" (ByVal strOutputFile As String, ByVal strPfxFile As String, ByVal nOptions As Long) As Long` `nRet = RSA_GetPrivateKeyFromPFX(strOutputFile, strPfxFile, nOptions) As Long` ### C/C++ Syntax `long __stdcall RSA_GetPrivateKeyFromPFX(const char *szFileOut, const char *szPfxFile, long nOptions);` ### Parameters *szFileOut* : [in] specifying the filename of the output file to be created. *szPfxFile* : [in] containing the PFX filename *nOptions* : [in] option flags: not used in this release. Specify zero. ### Returns (VBA/C) If successful, it returns the number of bytes written to the output file; otherwise it returns a negative [error code](#errorcodes). ### .NET Equivalent [Rsa.GetPrivateKeyFromPFX Method](#M_Rsa_GetPrivateKeyFromPFX) ### C++ (STL) Equivalent static int [dipki::Rsa::GetPrivateKeyFromPFX](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rsa.html#a238dd633405d9a5174a6a1762db151e7 "External link") (const std::string &outputFile, const std::string &pfxFile) ### Python Equivalent static [Rsa.get_privatekey_from_pfx](https://cryptosys.net/pki/pydocpki/class-stubs/Rsa.html#cryptosyspki.Rsa.get_privatekey_from_pfx "External link")(outputfile, pfxfile) ### Remarks The first `pkcs-12-pkcs-8ShroudedKeyBag` found in the PFX file will be extracted and saved directly as a BER-encoded `EncryptedPrivateKeyInfo` file. No decryption or other conversion is carried out. ### Example ``` nChars = RSA_GetPrivateKeyFromPFX(strEPKFile, strPfxFile, 0) ``` ### See Also [RSA_ReadEncPrivateKey](#RSA_ReadEncPrivateKey) [RSA_ReadPrivateKeyFromPFX](#RSA_ReadPrivateKeyFromPFX) [PFX_MakeFile](#PFX_MakeFile) [[Contents](#topofpage)] [[Index](#index)] RSA_GetPublicKeyFromCert ------------------------------------------------------------- Reads a public key from an X.509 certificate into an "internal" public key string. ### VBA/VB6 Syntax `Public Declare Function RSA_GetPublicKeyFromCert Lib "diCrPKI.dll" (ByVal strPublicKey As String, ByVal nOutChars As Long, ByVal strCertFileName As String, ByVal nOptions As Long) As Long` `nRet = RSA_GetPublicKeyFromCert(strPublicKey, nOutChars, strCertFileName, nOptions) As Long` ### C/C++ Syntax `long __stdcall RSA_GetPublicKeyFromCert(char *szOutput, long nOutChars, const char *szCertFile, long nOptions);` ### Parameters *szOutput* : [out] to receive encoded public key data. *nOutChars* : [in] specifying the maximum number of characters to be received. *szCertFile* : [in] specifying the filename of an X.509 certificate file (or [base64 representation](#base64forcert)). *nOptions* : [in] option flags: not used in this release. Specify zero. ### Returns (VBA/C) If successful, the return value is the number of characters in or required for the output string; otherwise it returns a negative [error code](#errorcodes). ### .NET Equivalent [Rsa.GetPublicKeyFromCert Method](#M_Rsa_GetPublicKeyFromCert) ### Remarks Call the function with an empty or NULL *szOutput* string or zero *nOutChars* parameter to find out the required length of the output string. C/C++ users should add one to this value when allocating memory. Both binary BER-encoded and PEM-style base64-encoded certificates can be read, or the certificate can be passed directly as a string in [base64 representation](#base64forcert). *Woops!* The name of this function is an exception to our usual convention that "Read" means read-into-internal-string and "Get" means extract-and-save-as-a-file. By rights this function should be called "RSA_**Read**PublicKeyFromCert". Sorry. ### Example This code reads Alice's public key from her certificate and saves in a PKCS#1 public key file. The certificate is from [[SMIME-EX]](#SMIME-EX). ``` Dim strCertFile As String Dim strKeyFile As String Dim strPublicKey As String Dim nChars As Long Dim nRet As Long strCertFile = "AliceRSASignByCarl.cer" ' First find out the length of string we need nChars = RSA_GetPublicKeyFromCert(vbNullString, 0, strCertFile, 0) Debug.Print "RSA_GetPublicKeyFromCert returns " & nChars & " (expecting +ve)" If nChars <= 0 Then Debug.Print "ERROR: " & pkiErrorLookup(nChars) Exit Sub End If ' Pre-dimension the string to receive data - IMPORTANT strPublicKey = String(nChars, " ") ' Read in the Public Key in our "internal" format nRet = RSA_GetPublicKeyFromCert(strPublicKey, nChars, strCertFile, 0) Debug.Print "Public key is " & RSA_KeyBits(strPublicKey) & " bits long" ' Now save as a PKCS#1 public key file strKeyFile = "AlicePubRSA.pub" nRet = RSA_SavePublicKey(strKeyFile, strPublicKey, 0) Debug.Print "RSA_SavePublicKey returns " & nRet If nRet = 0 Then Debug.Print "Saved as public key file '" & strKeyFile & "'" Else Debug.Print "ERROR: " & pkiErrorLookup(nRet) End If ``` This should result in the output: ``` RSA_GetPublicKeyFromCert returns 220 (expecting +ve) Public key is 1024 bits long RSA_SavePublicKey returns 0 Saved as public key file 'AlicePubRSA.pub' ``` ### See Also [RSA_SavePublicKey](#RSA_SavePublicKey) [RSA_PublicKeyFromPrivate](#RSA_PublicKeyFromPrivate) [X509_GetCertFromP7Chain](#X509_GetCertFromP7Chain) [X509_GetCertFromPFX](#X509_GetCertFromPFX) [[Contents](#topofpage)] [[Index](#index)] RSA_KeyBits ----------------------------------- Returns the length of key in bits given the public or private key string. ### VBA/VB6 Syntax `Public Declare Function RSA_KeyBits Lib "diCrPKI.dll" (ByVal strKey As String) As Long` `nRet = RSA_KeyBits(strKey)` ### C/C++ Syntax `long __stdcall RSA_KeyBits(const char *szKeyString);` ### Parameters *szKeyString* : [in] containing the RSA private or public key string. ### Returns (VBA/C) returns the number of significant bits in the key modulus or a negative [error code](#errorcodes). ### VBA Wrapper Syntax Public Function [`rsaKeyBits`](#VB_rsaKeyBits) (szKeyString As String) As Long ### .NET Equivalent [Rsa.KeyBits Method](#M_Rsa_KeyBits_String) (String) [Rsa.KeyBits Method](#M_Rsa_KeyBits_StringBuilder) (StringBuilder) ### C++ (STL) Equivalent static int [dipki::Rsa::KeyBits](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rsa.html#a6f495276f394a1eb0764e67c7d710206 "External link") (const std::string &keyStr) ### Python Equivalent static [Rsa.key_bits](https://cryptosys.net/pki/pydocpki/class-stubs/Rsa.html#cryptosyspki.Rsa.key_bits "External link")(keystr) ### Remarks ### Example ### See Also [RSA_KeyBytes](#RSA_KeyBytes) [[Contents](#topofpage)] [[Index](#index)] RSA_KeyBytes ------------------------------------- Returns the length of key in complete bytes (octets) given the public or private key string. ### VBA/VB6 Syntax `Public Declare Function RSA_KeyBytes Lib "diCrPKI.dll" (ByVal strKey As String) As Long` `nRet = RSA_KeyBytes(strKey)` ### C/C++ Syntax `long __stdcall RSA_KeyBytes(const char *szKeyString);` ### Parameters *szKeyString* : [in] containing the RSA private or public key string. ### Returns (VBA/C) returns the number of complete bytes (8-bit octets) in the key modulus or a negative [error code](#errorcodes). ### VBA Wrapper Syntax Public Function [`rsaKeyBytes`](#VB_rsaKeyBytes) (szKeyString As String) As Long ### .NET Equivalent [Rsa.KeyBytes Method](#M_Rsa_KeyBytes_String) (String) [Rsa.KeyBytes Method](#M_Rsa_KeyBytes_StringBuilder) (StringBuilder) ### C++ (STL) Equivalent static int [dipki::Rsa::KeyBytes](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rsa.html#a2f98ec43d53954c0eff33559b9ab07de "External link") (const std::string &keyStr) ### Python Equivalent static [Rsa.key_bytes](https://cryptosys.net/pki/pydocpki/class-stubs/Rsa.html#cryptosyspki.Rsa.key_bytes "External link")(keystr) ### Remarks Use this function to find out the required length of the encryption block for "raw" RSA encryption. ### Example ### See Also [RSA_KeyBits](#RSA_KeyBits) [RSA_RawPublic](#RSA_RawPublic) [RSA_RawPrivate](#RSA_RawPrivate) [[Contents](#topofpage)] [[Index](#index)] RSA_KeyHashCode ------------------------------------------- Computes the hash code of an "internal" RSA public or private key string. ### VBA/VB6 Syntax `Public Declare Function RSA_KeyHashCode Lib "diCrPKI.dll" (ByVal strKey As String) As Long` `nRet = RSA_KeyHashCode(strKey)` ### C/C++ Syntax `long __stdcall RSA_KeyHashCode(const char *szKeyString);` ### Parameters *szKeyString* : [in] containing the RSA private or public key string in internal format. ### Returns (VBA/C) A 32-bit hash code for the key, or zero on error. ### .NET Equivalent [Rsa.KeyHashCode Method](#M_Rsa_KeyHashCode_String) (String) [Rsa.KeyHashCode Method](#M_Rsa_KeyHashCode_StringBuilder) (StringBuilder) ### C++ (STL) Equivalent static uint32_t [dipki::Rsa::KeyHashCode](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rsa.html#a2a29511d1ba843a5024f1f5e4fc1dc16 "External link") (const std::string &intKeyString) ### Python Equivalent static [Rsa.key_hashcode](https://cryptosys.net/pki/pydocpki/class-stubs/Rsa.html#cryptosyspki.Rsa.key_hashcode "External link")(keystr) ### Remarks Use this function to compare internal key strings. As of version 3.0, internal key strings are encrypted and cannot be compared directly. The actual string values may or may not be the same even though the underlying key is. The hash code value will be the same for a given key. The hash code is computed to an internal algorithm and may return any integer value between -2,147,483,648 and 2,147,483,647. If the key string is invalid, the return value is zero and a nonzero error code will be set (use [`PKI_ErrorCode`](#PKI_ErrorCode) to check). There is a very small chance (one in 4 billion) that a valid key string returns a hash code of zero. ### Example See the example in [`RSA_ReadPrivateKeyInfo`](#RSA_ReadPrivateKeyInfo). ### See Also [RSA_KeyBits](#RSA_KeyBits) [RSA_KeyBytes](#RSA_KeyBytes) [[Contents](#topofpage)] [[Index](#index)] RSA_KeyMatch ------------------------------------- Verifies that a pair of "internal" RSA private and public key strings are matched. ### VBA/VB6 Syntax `Public Declare Function RSA_KeyMatch Lib "diCrPKI.dll" (ByVal strPrivateKey As String, ByVal strPublicKey As String) As Long` `nRet = RSA_KeyMatch(strPrivateKey, strPublicKey)` ### C/C++ Syntax `long __stdcall RSA_KeyMatch(const char *szPrivateKey, const char *szPublicKey);` ### Parameters *szPrivateKey* : [in] containing an "internal" RSA private key string. *szPublicKey* : [in] containing an "internal" RSA public key string. ### Returns (VBA/C) If the pair of private and public keys match, the return value is zero (0); if the key strings are valid but not matched, the return value is NO_MATCH_ERROR (-21). If an error occurs, it returns a nonzero [error code](#errorcodes). ### .NET Equivalent [Rsa.KeyMatch Method](#M_Rsa_KeyMatch_StringString) (String) [Rsa.KeyMatch Method](#M_Rsa_KeyMatch_StringBuilderStringBuilder) (StringBuilder) ### C++ (STL) Equivalent static bool [dipki::Rsa::KeyMatch](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rsa.html#a50c94da4020db9255ef92080d6d4fe52 "External link") (const std::string &priKeyStr, const std::string &pubKeyStr) ### Python Equivalent static [Rsa.key_match](https://cryptosys.net/pki/pydocpki/class-stubs/Rsa.html#cryptosyspki.Rsa.key_match "External link")(prikeystr, pubkeystr) ### Remarks This function allows you to check that a private key file is matched with the public key in an X.509 certificate. You must read the keys into "internal" key strings before comparing. Note that the return value for success is zero. ### Example ``` Dim strCertFile As String Dim strKeyFile As String Dim strPassword As String Dim strPublicKey As String Dim strPrivateKey As String Dim nRet As Long ' Input files strCertFile = "AAA010101AAAsd.cer" strKeyFile = "AAA010101AAA_0408021316S.key" ' Test password - CAUTION: DO NOT hardcode production passwords! strPassword = "Empresa1" ' Read in private key from encrypted .key file strPrivateKey = rsaReadPrivateKey(strKeyFile, strPassword) If Len(strPrivateKey) > 0 Then Debug.Print "Private key is " & RSA_KeyBits(strPrivateKey) & " bits" Else Debug.Print "ERROR: Cannot read private key file." Exit Sub End If ' Clean up password as we are done with it strPassword = wipeString(strPassword) ' Read in public key from certificate strPublicKey = rsaGetPublicKeyFromCert(strCertFile) If Len(strPublicKey) > 0 Then Debug.Print "Public key is " & RSA_KeyBits(strPublicKey) & " bits" Else Debug.Print "ERROR: Cannot read certificate file." Exit Sub End If ' See if the two key strings match nRet = RSA_KeyMatch(strPrivateKey, strPublicKey) If nRet = 0 Then Debug.Print "OK, key strings match." Else Debug.Print "FAILED: key strings do not match." End If ' Clean up private key string strPrivateKey = wipeString(strPrivateKey) ``` Using the sample Mexican Government SAT files, the output is as follows: ``` Private key is 1024 bits Public key is 1024 bits OK, key strings match. ``` ### See Also [RSA_KeyHashCode](#RSA_KeyHashCode) [[Contents](#topofpage)] [[Index](#index)] RSA_KeyValue ------------------------------------- Extracts a base64-encoded RSA key value from internal key string. ### VBA/VB6 Syntax `Public Declare Function RSA_KeyValue Lib "diCrPKI.dll" (ByVal strOutput As String, ByVal nOutChars As Long, ByVal strKeyString As String, ByVal strFieldName As String, ByVal nOptions As Long) As Long` `nRet = RSA_KeyValue(strOutput, nOutChars, strKeyString, strFieldName, nOptions)` ### C/C++ Syntax `long __stdcall RSA_KeyValue(char *szOutput, long nOutChars, const char *szKeyString, const char *szFieldName, long nOptions);` ### Parameters *szOutput* : [out] string of sufficient length to receive the output *nOutChars* : [in] specifying the maximum number of characters to be received *szKeyString* : [in] Public or private key in internal string format *szFieldName* : [in] Name of field to be extracted: `"Modulus"` or `"Exponent"` *nOptions* : [in] option flags. Set to zero. ### Returns (VBA/C) If successful, the return value is the number of characters in or required for the output string; otherwise it returns a negative [error code](#errorcodes). ### VBA Wrapper Syntax Public Function [`rsaKeyValue`](#VB_rsaKeyValue) (szKeyString As String, szFieldName As String, Optional nOptions As Long = 0) As String ### .NET Equivalent [Rsa.KeyValue Method](#M_Rsa_KeyValue) ### C++ (STL) Equivalent static std::string [dipki::Rsa::KeyValue](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rsa.html#a128b7ef2bae278e6b0856439e43d2e8d "External link") (const std::string &keyStr, const std::string &fieldName) ### Python Equivalent static [Rsa.key_value](https://cryptosys.net/pki/pydocpki/class-stubs/Rsa.html#cryptosyspki.Rsa.key_value "External link")(keystr, fieldname) ### Remarks For the "raw" VBA/C function, the user must allocate an output string buffer *szOutput* of the required length. Specify a zero *nOutChars* or an empty string for *szOutput* to find the required length. ANSI C users [must add one to this value](#cusersaddone) when allocating memory. The output is a continuous string of base64 characters suitable for a `` node in an XML-DSIG document. A typical `` node looks like this: ``` 4IlzOY3Y9fXoh3Y5f06wBbtTg94Pt6vcfcd1KQ0FLm0S36aGJtTSb6pYKfyX7PqCUQ8wgL6xUJ5GRPEsu9gyz8 ZobwfZsGCsvu40CWoT9fcFBZPfXro1Vtlh/xl/yYHm+Gzqh0Bw76xtLHSfLfpVOrmZdwKmSFKMTvNXOFd0V18= AQAB ``` Use this function to populate the fields `` and `` for a given RSA key, or to use the values in other computations. ### Example (VBA core function) ``` Dim nChars As Long Dim strKeyString As String Dim strFieldName As String Dim strValue As String ' Read in key to internal string strKeyString = rsaReadPublicKey("AliceRSASignByCarl.cer") strFieldName = "Modulus" nChars = RSA_KeyValue("", 0, strKeyString, strFieldName, 0) If (nChars < 0) Then Debug.Print "ERROR: " & pkiErrorLookup(nChars) Exit Sub End If ' Dimension output strValue = String(nChars, " ") nChars = RSA_KeyValue(strValue, nChars, strKeyString, strFieldName, 0) Debug.Print strFieldName & "=" & strValue strFieldName = "Exponent" nChars = RSA_KeyValue("", 0, strKeyString, strFieldName, 0) If (nChars < 0) Then Debug.Print "ERROR: " & pkiErrorLookup(nChars) Exit Sub End If ' Dimension output strValue = String(nChars, " ") nChars = RSA_KeyValue(strValue, nChars, strKeyString, strFieldName, 0) Debug.Print strFieldName & "=" & strValue ``` ``` Modulus=4IlzOY3Y9fXoh3Y5f06wBbt ... +Gzqh0Bw76xtLHSfLfpVOrmZdwKmSFKMTvNXOFd0V18= Exponent=AQAB ``` ### Example (VBA wrapper function) ``` Dim strKeyString As String Dim strFieldName As String Dim strValue As String strKeyString = rsaReadPublicKey("AliceRSASignByCarl.cer") strFieldName = "Modulus" strValue = rsaKeyValue(strKeyString, strFieldName) Debug.Print strFieldName & "=" & strValue strFieldName = "Exponent" strValue = rsaKeyValue(strKeyString, strFieldName) Debug.Print strFieldName & "=" & strValue ``` ### See Also [[Contents](#topofpage)] [[Index](#index)] RSA_MakeKeys ------------------------------------- Generate an RSA key pair and save as two key files. *[Superseded by* `[RSA_MakeKeysXtd](#RSA_MakeKeysXtd)`.] ### VBA/VB6 Syntax `Public Declare Function RSA_MakeKeys Lib "diCrPKI.dll" (ByVal strPubKeyFile As String, ByVal strPvkKeyFile As String, ByVal nBits As Long, ByVal nExpFermat As Long, ByVal nTests As Long, ByVal nCount As Long, ByVal strPassword As String, ByVal strSeed As String, ByVal nSeedLen As Long, ByVal nOptionFlags As Long) As Long` `nRet = RSA_MakeKeys(strPublicKeyFile, strPrivateKeyFile, nBits, nExpFermat, nTests, nCount, strPassword, strSeed, nSeedLen, nOptionFlags)` ### C/C++ Syntax `long __stdcall RSA_MakeKeys(const char *szPubKeyFile, const char *szEpkFile, long nBits, long nExpFermat, long nTests, long nCount, const char *szPassword, const void *lpSeed, long nSeedLen, long nOptions);` ### Parameters *szPubKeyFile* : [in] name of public key file to be created. *szEpkFile* : [in] name of encrypted private key file to be created. *nBits* : [in] required key size in bits (minimum 96). *nExpFermat* : [in] exponent *e* to be used. Select from: `PKI_RSAEXP_EQ_3` for 3 `PKI_RSAEXP_EQ_5` for 5 `PKI_RSAEXP_EQ_17` for 17 (0x11) `PKI_RSAEXP_EQ_257` for 257 (0x101) `PKI_RSAEXP_EQ_65537` for 65537 (0x10001) (default) *nTests* : [in] specifying the number of Rabin-Miller tests to be performed (recommended at least 50). *nCount* : [in] specifying the iteration count to be used when encrypting the private key (default = 1; recommended at least 1000). *szPassword* : [in] password to be used to encrypt the private key file. *lpSeed* : [in] an (optional) user-specified seed to be used by the random number generator (specify "" or NULL to ignore). *nSeedLen* : [in] length of the seed in bytes. *nOptions* : [in] a flag to indicate the algorithm to be used to encrypt the private key file. Select from: `PKI_PBE_SHA_3DES` (0) for `"pbeWithSHAAnd3-KeyTripleDES-CBC"` (default) or `PKI_PBE_PBES2` for `"pkcs5PBES2"` plus one of * `PKI_BC_DESEDE3` to use `des-EDE3-CBC` (default) * `PKI_BC_AES128` to use `AES128-CBC` * `PKI_BC_AES192` to use `AES192-CBC` * `PKI_BC_AES256` to use `AES256-CBC` (there are more options - see [security options for encrypted private keys](#encryptedkeyoptions)) and optionally add `PKI_KEYGEN_INDICATE` to indicate progress in a console window (see remarks below), plus one of `PKI_KEY_FORMAT_PEM` to save the key files in PEM form (default is binary BER-encoded format) *or* `PKI_KEY_FORMAT_SSL` to save the key files in PEM form with the public key as an OpenSSL-compatible subjectPublicKeyInfo file. ### Returns (VBA/C) If successful, the return value is zero; otherwise it returns a nonzero [error code](#errorcodes). ### VBA Wrapper Syntax Public Function [`rsaMakeKeys`](#VB_rsaMakeKeys) (szPubKeyFile As String, szPriKeyFile As String, szPassword As String, nBits As Long, Optional nExpFermat As Long = PKI_RSAEXP_EQ_65537, Optional szParams As String = "", Optional nOptions As Long = 0) As Long ### .NET Equivalent [Rsa.MakeKeys Method](#M_Rsa_MakeKeys_StringStringInt32Rsa_PublicExponentInt32StringRsa_PbeOptionsBooleanByte) (String, String, Int32, Rsa.PublicExponent, Int32, String, Rsa.PbeOptions, Boolean, Byte[]) [Rsa.MakeKeys Method](#M_Rsa_MakeKeys_StringStringInt32Rsa_PublicExponentInt32StringCipherAlgorithmHashAlgorithmRsa_FormatBoolean) (String, String, Int32, Rsa.PublicExponent, Int32, String, CipherAlgorithm, HashAlgorithm, Rsa.Format, Boolean) ### C++ (STL) Equivalent static int [dipki::Rsa::MakeKeys](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rsa.html#a48dfe8237977369f90405443169a1bce "External link") (const std::string &publicKeyFile, const std::string &privateKeyFile, const std::string &password, int nbits, PublicExponent exponent=PublicExponent::Exp_EQ_65537, PbeScheme pbes=PbeScheme::Default, const std::string ¶mString="", Format fileFormat=Format::Binary, bool showProgress=false) ### Remarks The RSA key is stored by default as a pair of DER-encoded binary files. The public and private keys are encoded into ASN.1 values of type `RSAPublicKey` and `RSAPrivateKey` respectively (defined in PKCS #1). The private key is then encrypted and encoded into a PKCS #8 `EncryptedPrivateKeyInfo` type. Any existing files of the same names will be overwritten without warning. The key length must be greater than 96 bits. The value of the exponent is limited to the five values listed. The password and iteration count are used to encrypt the private key according to the specified PBE algorithm specified in *nOptionFlags*. The password should be a string of ASCII characters and must not contain any NUL characters (i.e. `Chr(0)`). The seed is optional and is used to supplement the seeding of the random number generator. The user may use the seed to provide some additional value ("user-supplied entropy") that is unique when the keys are being generated. See [Random Number Generator and Seeds](#rnginfo) for more information. The default format for the files is binary DER-encoded format. Use either the `PKI_KEY_FORMAT_PEM` *or* the `PKI_KEY_FORMAT_SSL` flag to save in base64 "PEM" format. Files saved with the `PKI_KEY_FORMAT_SSL` flag should be compatible with OpenSSL. For more details on the formats, see `[RSA_SavePublicKey()](#RSA_SavePublicKey)` and `[RSA_SaveEncPrivateKey()](#RSA_SaveEncPrivateKey)`. Generating RSA key pairs can take some time. On a 1GHz P3 test machine, the following times were typical: | Key size | Time | | --- | --- | | 512 | < 1 second | | 1024 | 5 seconds | | 2048 | 1 minute | | 4096 | 6 minutes | | 8192 | 1 hour | Some programs like Office Access will get bored waiting for the longer processes to finish and may hang. Setting the `PKI_KEYGEN_INDICATE` flag will show progress in a separate console window (actually two, one for p and one for q). Having a console window show progress will keep the parent application happy. A dot "." indicates a new candidate is being tested, and an asterisk "*" indicates that a Rabin-Miller test has been carried out (that is the expensive part of the process). The program will close these console windows down automatically. Do not use the `PKI_KEYGEN_INDICATE` option in a multi-threaded environment. For console-based programs, this option just shows the progress in the standard output. **Caution:** pressing Ctrl-C or Ctrl-Break in the console window will kill your entire process altogether; that is, abort your whole application, which may not be what you want. There is a very, very small possibility that the generator may fail to find a suitable prime number candidate within the number of iterations it carries out. If this happens (we've never seen it, but it could in theory), the function will return a `KEYGEN_FAILED_ERROR` error code 24. This in itself does not indicate a systemic problem with the Toolkit, just an incredibly unlucky event. Let us know if it happens more than once. ### Example ``` Dim nRet As Long Dim sPublicKeyFile As String Dim sPrivateKeyFile As String Dim sPassword As String sPublicKeyFile = "mykey.pub" sPrivateKeyFile = "mykey.p8e" sPassword = "password" ' Create a new pair of RSA keys saved as BER-encoded files Debug.Print "About to create a new RSA key pair..." nRet = RSA_MakeKeys(sPublicKeyFile, sPrivateKeyFile, 512, _ PKI_RSAEXP_EQ_3, 50, 1000, sPassword, "", 0, 0) Debug.Print "RSA_MakeKeys returns " & nRet & " (expected 0)" ``` The example above will generate a 512-bit RSA key pair and store in two files, a public key file `mykey.pub` and an encrypted private key file `mykey.p8e`. The exponent will be 3. Rabin-Miller tests will be carried out 50 times to verify that the values of p and q are prime. The private key will be encrypted using the default `"pbeWithSHAAnd3-KeyTripleDES-CBC"` algorithm using the password "password" and an iteration count of 1000. ``` strSeed = "yyyseed345" nRet = RSA_MakeKeys(sPublicKeyFile, sPrivateKeyFile, 2048, PKI_RSAEXP_EQ_65537, 64, 3000, "94tMhvTr7gvVy48q", strSeed, Len(strSeed), PKI_PBE_PBKDF2_AES128) ``` The second example generates a 2048-bit RSA key pair with the exponent 65537 (0x10001). Sixty-four Rabin-Miller tests are used to test for primality. The private key will be encrypted using the PBES2 algorithm with AES-128 as the encryption scheme, the password "94tMhvTr7gvVy48q", and an iteration count of 3000. The string "yyyseed345" will be added to the RNG seeding process. Note the use of `PKI_PBE_PBKDF2_AES128` as a replacement for the older (but still valid) option `PKI_PBE_PBES2+PKI_BC_AES128`. ### See Also [RSA_ReadEncPrivateKey](#RSA_ReadEncPrivateKey) [RSA_ReadPublicKey](#RSA_ReadPublicKey) [RSA_SaveEncPrivateKey](#RSA_SaveEncPrivateKey) [RSA_SavePublicKey](#RSA_SavePublicKey) [[Contents](#topofpage)] [[Index](#index)] RSA_MakeKeysXtd ------------------------------------------- Generate an RSA key pair and save as two key files. ### VBA/VB6 Syntax `Public Declare Function RSA_MakeKeysXtd Lib "diCrPKI.dll" (ByVal strPubKeyFile As String, ByVal strPriKeyFile As String, ByVal strPassword As String, ByVal nBits As Long, ByVal nExpFermat As Long, ByVal strParams As String, ByVal nOptions As Long) As Long` `nRet = RSA_MakeKeysXtd(strPubKeyFile, strPriKeyFile, strPassword, nBits, nExpFermat, strParams, nOptionFlags)` ### C/C++ Syntax `long __stdcall RSA_MakeKeysXtd(const char *szPubKeyFile, const char *szPriKeyFile, const char *szPassword, long nBits, long nExpFermat, const char *szParams, long nOptions);` ### Parameters *szPubKeyFile* : [in] Output filename for public key. *szPriKeyFile* : [in] Output filename for (encrypted) private key. *szPassword* : [in] Password for encrypted private key (required). *nBits* : [in] Required key modulus size in bits (minimum 96). *nExpFermat* : [in] exponent *e* to be used. Select from: `PKI_RSAEXP_EQ_3` for 3 `PKI_RSAEXP_EQ_5` for 5 `PKI_RSAEXP_EQ_17` for 17 (0x11) `PKI_RSAEXP_EQ_257` for 257 (0x101) `PKI_RSAEXP_EQ_65537` for 65537 (0x10001) (default) *szParams* : [in] Optional parameters. Set as the empty string `""` for defaults. Otherwise include a set of attribute-value pairs separated by a semi-colon ";" to set options from the following * `count=` to set the iteration count in the encrypted private key used in the PBKDF method, e.g. `"count=5000;"` [default=`2048`] * `prf=` to change the HMAC algorithm used in the PBKDF2 method, e.g. `"prf=hmacWithSHA256;"` [default=`hmacwithSHA1`] * `rngseed=` to add some extra user-specified additional seed for the random number generator, e.g. `"rngseed=pqrrr1234xyz;"` Valid values for hmac-name are `{hmacWithSHA1|hmacWithSHA224|hmacWithSHA256|hmacWithSHA384|hmacWithSHA512}`. *nOptions* : [in] a flag to indicate the password-based encryption scheme to be used to encrypt the private key file. Select from: `PKI_PBE_SHA_3DES` (0) for `"pbeWithSHAAnd3-KeyTripleDES-CBC"` from PKCS12 (default) `PKI_PBE_PBKDF2_DESEDE3` for PBKDF2 using `des-EDE3-CBC` `PKI_PBE_PBKDF2_AES128` for PBKDF2 using `aes128-CBC` `PKI_PBE_PBKDF2_AES192` for PBKDF2 using `aes192-CBC` `PKI_PBE_PBKDF2_AES256` for PBKDF2 using `aes256-CBC` (there are more options - see [security options for encrypted private keys](#encryptedkeyoptions)) and optionally add `PKI_KEYGEN_INDICATE` to indicate progress in a console window (see remarks below), plus one of `PKI_KEY_FORMAT_PEM` to save the key files in PEM form (default is binary DER-encoded format) *or* `PKI_KEY_FORMAT_SSL` to save the key files in PEM form with the public key as an OpenSSL-compatible subjectPublicKeyInfo file. ### Returns (VBA/C) If successful, the return value is zero; otherwise it returns a nonzero [error code](#errorcodes). ### .NET Equivalent [Rsa.MakeKeys Method](#M_Rsa_MakeKeys_StringStringStringInt32Rsa_PublicExponentRsa_PbeOptionsStringRsa_FormatBoolean) ### Python Equivalent static [Rsa.make_keys](https://cryptosys.net/pki/pydocpki/class-stubs/Rsa.html#cryptosyspki.Rsa.make_keys "External link")(pubkeyfile, prikeyfile, nbits, exponent, password, pbes=0, params='', fileformat=0) ### Remarks The RSA keys are stored by default as a pair of DER-encoded binary files. Setting the `PKI_KEYGEN_INDICATE` flag will show progress in a separate console window (actually two, one for p and one for q). Having a console window show progress will keep a parent application (like MS Access) happy and prevent it hanging due to boredom. The program will close these console windows down automatically (do not use Ctrl-C or Ctrl-Break: it will kill your entire process altogether!). Do not use the `PKI_KEYGEN_INDICATE` option in a multi-threaded environment. For console-based programs, this option just shows the progress in the standard output. ### Example (VBA core function) ``` ``` ### Example (VBA wrapper function) ``` Dim r As Long ' Create a 2048-bit RSA key pair using defaults r = rsaMakeKeys("myrsa2048.pub", "myrsa2048.p8e", "password", 2048) ' Same but using stronger security and in PEM format r = rsaMakeKeys("myrsa2048ex.pub", "myrsa2048ex.p8e", "password1", 2048,,"count=6000;prf=hmacWithSHA256", PKI_PBE_PBKDF2_AES128 Or PKI_KEY_FORMAT_PEM) ``` ### See Also [[Contents](#topofpage)] [[Index](#index)] RSA_PublicKeyFromPrivate ------------------------------------------------------------- Converts an internal RSA private key string into an internal public key string. ### VBA/VB6 Syntax `Public Declare Function RSA_PublicKeyFromPrivate Lib "diCrPKI.dll" (ByVal strOutput As String, ByVal nOutChars As Long, ByVal strKeyString As String, ByVal nOptions As Long) As Long` `nRet = RSA_PublicKeyFromPrivate(strOutput, nOutChars, strKeyString, nOptions) As Long` ### C/C++ Syntax `long __stdcall RSA_PublicKeyFromPrivate(char *szOutput, long nOutChars, const char *szKeyString, long nOptions);` ### Parameters *szOutput* : [out] to receive public key data in encoded "internal" format. *nOutChars* : [in] specifying the maximum number of characters to be received. *szKeyString* : [in] containing a private key in "internal" format. *nOptions* : [in] option flags: not used in this release. Specify zero. ### Returns (VBA/C) If successful, the return value is the number of characters in or required for the output string; otherwise it returns a negative [error code](#errorcodes). ### VBA Wrapper Syntax Public Function [`rsaPublicKeyFromPrivate`](#VB_rsaPublicKeyFromPrivate) (szKeyString As String, Optional nOptions As Long = 0) As String ### .NET Equivalent [Rsa.PublicKeyFromPrivate Method](#M_Rsa_PublicKeyFromPrivate) ### C++ (STL) Equivalent static std::string [dipki::Rsa::PublicKeyFromPrivate](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rsa.html#a32a2360cf76e4930b1a55950afdc6da4 "External link") (const std::string &keyStr) ### Python Equivalent static [Rsa.publickey_from_private](https://cryptosys.net/pki/pydocpki/class-stubs/Rsa.html#cryptosyspki.Rsa.publickey_from_private "External link")(intkeystr) ### Remarks For the "raw" VBA/C function, the user must allocate an output string buffer *szOutput* of the required length. Specify a zero *nOutChars* or an empty string for *szOutput* to find the required length. ANSI C users [must add one to this value](#cusersaddone) when allocating memory. Use this function if you need a public key string but only have the corresponding private key file. The format used to store RSA private keys contains both the public and private components (that is, *n* and *e* are present in both) so we can obtain the public key from its corresponding private key. Note that internal key strings are only valid for the current session. ### Example (VBA core function) This example reads in a private key to an internal private key string, displays some information about the key, then converts it to a public key string and displays its properties. ``` Dim strPriKeyFile As String Dim strPrivateKey As String Dim strPublicKey As String Dim nChars As Long Dim nCode As Long Dim nRet As Long ' Read private key from encrypted private key file into internal string form strPriKeyFile = "BobPrivRSAEncrypt.p8e" strPrivateKey = rsaReadPrivateKey(strPriKeyFile, "password") If Len(strPrivateKey) = 0 Then Exit Sub 'Catch error here ' Display some info about it Debug.Print "Private key length = " & RSA_KeyBits(strPrivateKey) & " bits" nCode = RSA_KeyHashCode(strPrivateKey) Debug.Print "KeyHashCode=" & Hex(nCode) nRet = RSA_CheckKey(strPrivateKey, 0) Debug.Print "RSA_CheckKey returns " & nRet & ": (PKI_VALID_PRIVATEKEY=" & PKI_VALID_PRIVATEKEY & ")" ' Convert to public key string nChars = RSA_PublicKeyFromPrivate("", 0, strPrivateKey, 0) If nChars <= 0 Then Exit Sub ' Catch error here strPublicKey = String(nChars, " ") nChars = RSA_PublicKeyFromPrivate(strPublicKey, Len(strPublicKey), strPrivateKey, 0) ' Display some info about it Debug.Print "Public key length = " & RSA_KeyBits(strPublicKey) & " bits" nCode = RSA_KeyHashCode(strPublicKey) Debug.Print "KeyHashCode=" & Hex(nCode) nRet = RSA_CheckKey(strPublicKey, 0) Debug.Print "RSA_CheckKey returns " & nRet & ": (PKI_VALID_PUBLICKEY=" & PKI_VALID_PUBLICKEY & ")" ' Clean up strPrivateKey = wipeString(strPrivateKey) ``` Note that the KeyHashCodes and bit lengths are the same. ``` Private key length = 1024 bits KeyHashCode=6BCC120C RSA_CheckKey returns 0: (PKI_VALID_PRIVATEKEY=0) Public key length = 1024 bits KeyHashCode=6BCC120C RSA_CheckKey returns 1: (PKI_VALID_PUBLICKEY=1) ``` ### Example (VBA wrapper function) ``` Dim strPrivateKey As String Dim strPublicKey As String ' Read in private key to internal string strPrivateKey = rsaReadPrivateKey("BobPrivRSAEncrypt.p8e", "password") Debug.Assert Len(strPrivateKey) > 0 Debug.Print "Private key length = " & RSA_KeyBits(strPrivateKey) & " bits" Debug.Print "KeyHashCode=0x" & Hex(RSA_KeyHashCode(strPrivateKey)) ' Convert to public key string strPublicKey = rsaPublicKeyFromPrivate(strPrivateKey) Debug.Print "Public key length = " & RSA_KeyBits(strPublicKey) & " bits" Debug.Print "KeyHashCode=0x" & Hex(RSA_KeyHashCode(strPublicKey)) ``` ### See Also [RSA_SavePublicKey](#RSA_SavePublicKey) [RSA_ReadEncPrivateKey](#RSA_ReadEncPrivateKey) [[Contents](#topofpage)] [[Index](#index)] RSA_RawPrivate ----------------------------------------- Transforms (that is, encrypts or decrypts) raw data using an RSA private key. ### VBA/VB6 Syntax `Public Declare Function RSA_RawPrivate Lib "diCrPKI.dll" (ByRef lpData As Byte, ByVal nDataLen As Long, ByVal strPrivateKey As String, ByVal nOptions As Long) As Long` `nRet = RSA_RawPrivate(lpData(0), nDataLen, strPrivateKey, nOptions)` ### C/C++ Syntax `long __stdcall RSA_RawPrivate(unsigned char *lpData, long nDataLen, const char *szPrivateKey, long nOptions);` ### Parameters *lpData* : [in,out] array containing the data to be transformed. *nDataLen* : [in] specifying the number of bytes of data. *szPrivateKey* : [in] containing the RSA private key string. *nOptions* : [in] option flags. Set to zero. ### Returns (VBA/C) If successful, the return value is zero; otherwise it returns a nonzero [error code](#errorcodes). ### VBA Wrapper Syntax Public Function [`rsaRawPrivate`](#VB_rsaRawPrivate) (lpData() As Byte, szPrivateKey As String, Optional nOptions As Long = 0) As Byte() ### .NET Equivalent [Rsa.RawPrivate Method](#M_Rsa_RawPrivate_ByteString) (Byte[], String) [Rsa.RawPrivate Method](#M_Rsa_RawPrivate_ByteStringInt32) (Byte[], String, Int32) ### C++ (STL) Equivalent static bvec_t [dipki::Rsa::RawPrivate](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rsa.html#a50a88a4e9650c3e384e25135eb8e6dd5 "External link") (const bvec_t &data, const std::string &keyStr) ### Python Equivalent static [Rsa.raw_private](https://cryptosys.net/pki/pydocpki/class-stubs/Rsa.html#cryptosyspki.Rsa.raw_private "External link")(block, prikeystr) ### Remarks The data must be the same length as the RSA key modulus (use `RSA_KeyBytes()` to find out this). The output is written over the input. The RSA private key must be provided in the internal key string format. ### Example (VBA core function) This is adapted from "Some Examples of the PKCS Standards: An RSA Laboratories Technical Note", Burton S. Kaliski Jr., 1993 [[PKCS-EX](#PKCS-EX)]. It carries out the signing of the encryption block from section 3.2 using the 508-bit private key and then verifies the signature using the corresponding public key. The keys are stored in files `rsa508.pub` and `rsa508.p8e`. ``` Dim strEPKFile As String Dim strPubFile As String Dim strPassword As String Dim strPublicKey As String Dim strPrivateKey As String Dim nRet As Long Dim strOutputFile As String Dim abData() As Byte Dim nDataLen As Long Dim sHexData As String strEPKFile = "rsa508.p8e" strPassword = "password" ' Read in the deciphered private key string strPrivateKey = rsaReadPrivateKey(strEPKFile, strPassword) If Len(strPrivateKey) = 0 Then MsgBox "Unable to retrieve private key" Exit Function End If Debug.Print strPrivateKey ' Create some raw data to be RSA'd ' Ref: 3.2 Signing the CertificationRequestInfo encoding ' 64-octet EB in full: '00 01 ff ff ff ff ff ff ff ff ff ff ff ff ff ff 'ff ff ff ff ff ff ff ff ff ff ff ff ff 00 30 20 '30 0c 06 08 2a 86 48 86 f7 0d 02 02 05 00 04 10 'dc a9 ec f1 c1 5c 1b d2 66 af f9 c8 79 93 65 cd sHexData = "0001ffffffffffffffffffffffffffff" & _ "ffffffffffffffffffffffffff003020" & _ "300c06082a864886f70d020205000410" & _ "dca9ecf1c15c1bd266aff9c8799365cd" abData = cnvBytesFromHexStr(sHexData) nDataLen = UBound(abData) - LBound(abData) + 1 Debug.Print "Input: " & cnvHexStrFromBytes(abData) ' Now we have our data in a byte array and ' our private key in string format, ' we are ready to do a "raw" operation nRet = RSA_RawPrivate(abData(0), nDataLen, strPrivateKey, 0) Debug.Print "RSA_RawPrivate returns " & nRet If nRet <> 0 Then Debug.Print pkiGetLastError() Else ' Display our results in hex format Debug.Print "Output: " & cnvHexStrFromBytes(abData) End If ' Get the corresponding Public Key, also in a file strPubFile = "rsa508.pub" strPublicKey = rsaReadPublicKey(strPubFile) Debug.Print strPublicKey ' Do a "raw" encryption with the public key nRet = RSA_RawPublic(abData(0), nDataLen, strPublicKey, 0) Debug.Print "RSA_RawPublic returns " & nRet If nRet <> 0 Then Debug.Print pkiGetLastError() Else ' Display our results in hex format Debug.Print "Decrypt:" & cnvHexStrFromBytes(abData) End If ``` ### Example (VBA wrapper function) ``` Dim strPrivateKey As String Dim pt() As Byte Dim ct() As Byte strPrivateKey = rsaReadPrivateKey("rsa508.p8e", "password") Debug.Assert Len(strPrivateKey) > 0 pt = cnvBytesFromHexStr("0001ffffffffffffffffffffffffffff" & _ "ffffffffffffffffffffffffff003020" & _ "300c06082a864886f70d020205000410" & _ "dca9ecf1c15c1bd266aff9c8799365cd") ct = rsaRawPrivate(pt, strPrivateKey) Debug.Print "CT=" & cnvHexStrFromBytes(ct) Dim strPublicKey As String Dim dt() As Byte strPublicKey = rsaReadPublicKey("Rsa508.pub") Debug.Assert Len(strPublicKey) > 0 dt = rsaRawPublic(ct, strPublicKey) Debug.Print "DT=" & cnvHexStrFromBytes(dt) ``` ### See Also [RSA_RawPublic](#RSA_RawPublic) [RSA_EncodeMsg](#RSA_EncodeMsg) [Raw RSA Techniques](#rawrsa) [[Contents](#topofpage)] [[Index](#index)] RSA_RawPublic --------------------------------------- Transforms (that is, encrypts or decrypts) raw data using an RSA public key. ### VBA/VB6 Syntax `Public Declare Function RSA_RawPublic Lib "diCrPKI.dll" (ByRef lpData As Byte, ByVal nDataLen As Long, ByVal strPublicKey As String, ByVal nOptions As Long) As Long` `nRet = RSA_RawPublic(lpData(0), nDataLen, strPublicKey, nOptions)` ### C/C++ Syntax `long __stdcall RSA_RawPublic(unsigned char *lpData, long nDataLen, const char *szPublicKey, long nOptions);` ### Parameters *lpData* : [in,out] array containing the data to be transformed. *nDataLen* : [in] specifying the number of bytes of data. *szPublicKey* : [in] containing the RSA public key string. *nOptions* : [in] option flags. Set to zero. ### Returns (VBA/C) If successful, the return value is zero; otherwise it returns a nonzero [error code](#errorcodes). ### VBA Wrapper Syntax Public Function [`rsaRawPublic`](#VB_rsaRawPublic) (lpData() As Byte, szPublicKey As String, Optional nOptions As Long = 0) As Byte() ### .NET Equivalent [Rsa.RawPublic Method](#M_Rsa_RawPublic_ByteString) (Byte[], String) [Rsa.RawPublic Method](#M_Rsa_RawPublic_ByteStringInt32) (Byte[], String, Int32) ### C++ (STL) Equivalent static bvec_t [dipki::Rsa::RawPublic](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rsa.html#aa9095099ada24c1489840cfa53ec83e3 "External link") (const bvec_t &data, const std::string &keyStr) ### Python Equivalent static [Rsa.raw_public](https://cryptosys.net/pki/pydocpki/class-stubs/Rsa.html#cryptosyspki.Rsa.raw_public "External link")(block, pubkeystr) ### Remarks The data must be the same length as the RSA key modulus (use `RSA_KeyBytes()` to find out this). The output is written over the input. The RSA public key must be provided in the internal key string format. ### Example (VBA core function) This is from Example 4.2 of [[SMIME-EX]](#SMIME-EX): ``` Dim sEncDataHex As String Dim abData() As Byte Dim nDataLen As Long Dim strCertFile As String Dim nKeyLen As Long Dim strPublicKey As String Dim nRet As Long ' Cut and paste from DUMPASN1 output sEncDataHex = "2F 23 82 D2 F3 09 5F B8 0C 58 EB 4E" & _ "9D BF 89 9A 81 E5 75 C4 91 3D D3 D0" & _ "D5 7B B6 D5 FE 94 A1 8A AC E3 C4 84" & _ "F5 CD 60 4E 27 95 F6 CF 00 86 76 75" & _ "3F 2B F0 E7 D4 02 67 A7 F5 C7 8D 16" & _ "04 A5 B3 B5 E7 D9 32 F0 24 EF E7 20" & _ "44 D5 9F 07 C5 53 24 FA CE 01 1D 0F" & _ "17 13 A7 2A 95 9D 2B E4 03 95 14 0B" & _ "E9 39 0D BA CE 6E 9C 9E 0C E8 98 E6" & _ "55 13 D4 68 6F D0 07 D7 A2 B1 62 4C" & _ "E3 8F AF FD E0 D5 5D C7" ' Convert to bytes abData = cnvBytesFromHexStr(sEncDataHex) ' Check Debug.Print cnvHexStrFromBytes(abData) strCertFile = "AliceRSASignByCarl.cer" ' Read in PublicKey as base64 string - pre-dimension first nKeyLen = RSA_GetPublicKeyFromCert("", 0, strCertFile, 0) Debug.Print "KeyLen = " & nKeyLen If nKeyLen <= 0 Then Debug.Print pkiGetLastError() MsgBox "Unable to retrieve private key" Exit Function End If ' Pre-dimension the string to receive data strPublicKey = String(nKeyLen, " ") ' Read in the Key nRet = RSA_GetPublicKeyFromCert(strPublicKey, nKeyLen, strCertFile, 0) Debug.Print "PubKey= " & strPublicKey ' Verify using the public key nDataLen = UBound(abData) + 1 Debug.Print "Input: " & cnvHexStrFromBytes(abData) nRet = RSA_RawPublic(abData(0), nDataLen, strPublicKey, 0) Debug.Print "Output: " & cnvHexStrFromBytes(abData) ``` Stripping the PKCS-1.5 header `0001FFFF...FF00` from the output, we should get ``` 3021300906052B0E03021A05000414406AEC085279BA6E16022D9E0629C0229687DD48 ``` which is a DigestInfo containing the 20-byte SHA-1 hash ``` 406AEC085279BA6E16022D9E0629C0229687DD48 ``` ### Example (VBA wrapper function) ``` Dim strPrivateKey As String Dim pt() As Byte Dim ct() As Byte strPrivateKey = rsaReadPrivateKey("rsa508.p8e", "password") Debug.Assert Len(strPrivateKey) > 0 pt = cnvBytesFromHexStr("0001ffffffffffffffffffffffffffff" & _ "ffffffffffffffffffffffffff003020" & _ "300c06082a864886f70d020205000410" & _ "dca9ecf1c15c1bd266aff9c8799365cd") ct = rsaRawPrivate(pt, strPrivateKey) Debug.Print "CT=" & cnvHexStrFromBytes(ct) Dim strPublicKey As String Dim dt() As Byte strPublicKey = rsaReadPublicKey("Rsa508.pub") Debug.Assert Len(strPublicKey) > 0 dt = rsaRawPublic(ct, strPublicKey) Debug.Print "DT=" & cnvHexStrFromBytes(dt) ``` ### See Also [RSA_RawPrivate](#RSA_RawPrivate) [RSA_EncodeMsg](#RSA_EncodeMsg) [Raw RSA Techniques](#rawrsa) [[Contents](#topofpage)] [[Index](#index)] RSA_ReadAnyPrivateKey ------------------------------------------------------- Reads from a file or string containing a private key into an "internal" private key string. ### VBA/VB6 Syntax `Public Declare Function RSA_ReadAnyPrivateKey Lib "diCrPKI.dll" (ByVal strOutput As String, ByVal nOutChars As Long, ByVal strKeyFileOrString As String, ByVal strPassword As String, ByVal nOptions As Long) As Long` `nRet = RSA_ReadAnyPrivateKey(strOutput, nOutChars, strKeyFileOrString, strPassword, nOptions) As Long` ### C/C++ Syntax `long __stdcall RSA_ReadAnyPrivateKey(char *szOutput, long nOutChars, const char *szKeyFileOrString, const char *szPassword, long nOptions);` ### Parameters *szOutput* : [out] to receive encoded private key data in "internal" format. *nOutChars* : [in] specifying the maximum number of characters to be received. *szKeyFileOrString* : [in] specifying either the name of file containing the private key or a string containing the key in [PEM format](#pemstring) or XML format. *szPassword* : [in] containing the password, if the key is encrypted, or `""` if not encrypted. *nOptions* : [in] not used in this release. Specify zero. ### Returns (VBA/C) If successful, the return value is the number of characters in or required for the output string; otherwise it returns a negative [error code](#errorcodes). ### VBA Wrapper Syntax Public Function [`rsaReadAnyPrivateKey`](#VB_rsaReadAnyPrivateKey) (szKeyFileOrString As String, Optional szPassword As String = "", Optional nOptions As Long = 0) As String Public Function [`rsaReadPrivateKey`](#VB_rsaReadPrivateKey) (szKeyFileOrString As String, Optional szPassword As String = "", Optional nOptions As Long = 0) As String ### .NET Equivalent [Rsa.ReadPrivateKey Method](#M_Rsa_ReadPrivateKey) ### C++ (STL) Equivalent static std::string [dipki::Rsa::ReadPrivateKey](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rsa.html#a1e2eff6eac9764624ed7d9eaf23b8f7a "External link") (const std::string &keyFileOrString, const std::string &password="") ### Python Equivalent static [Rsa.read_private_key](https://cryptosys.net/pki/pydocpki/class-stubs/Rsa.html#cryptosyspki.Rsa.read_private_key "External link")(keyfileorstr, password="") ### Remarks For the "raw" VBA/C function, the user must allocate an output string buffer *szOutput* of the required length. Specify a zero *nOutChars* or an empty string for *szOutput* to find the required length. ANSI C users [must add one to this value](#cusersaddone) when allocating memory. This function will attempt to read the private key from "any" supported format. The output will be an ephemeral "internal" key string suitable for the current session only. Supported formats are: * Encrypted or unencrypted PKCS#8 private key (.p8e, .p8) file in either binary DER format or text PEM format * PKCS#12 (.p12, .pfx) file containing a PKCSShroudedKeyBag. *[v20.5]* Added support for AES256-SHA256 encryption. * OpenSSL-compatible PKCS#1 RSA private key file in either binary DER format or text PEM format * String containing contents of any of the above files in text form as a [PEM string](#pemstring) * XML file or string containing an XKMS-conforming `RSAKeyPair` element * JSON file or string containing a plaintext RSA private key represented in JSON Web Key (JWK) format. This supersedes the following functions: * `RSA_ReadEncPrivateKey` * `RSA_ReadPrivateKeyInfo` * `RSA_ReadPrivateKeyFromPFX` ### Example (VBA core function) This VB6/VBA wrapper function returns the "internal" private key string given the filename and password ``` Public Function rsaReadPrivateKey(strKeyFileOrString As String, strPassword As String) As String ' Reads the private key from any supported private key file or PEM string ' Returns the key as an ephemeral base64 string or an empty string on error Dim nChars As Long ' How long is PrivateKey string? nChars = RSA_ReadAnyPrivateKey("", 0, strKeyFileOrString, strPassword, 0) If nChars <= 0 Then Exit Function End If ' Pre-dimension the string to receive data rsaReadPrivateKey = String(nChars, " ") ' Read in the Private Key nChars = RSA_ReadAnyPrivateKey(rsaReadPrivateKey, nChars, strKeyFileOrString, strPassword, 0) End Function ``` ### Example (VBA wrapper function) ``` Dim strIntKey As String strIntKey = rsaReadAnyPrivateKey("AlicePrivRSASign.p8e", "password") Debug.Print strIntKey Debug.Print "KeyHashCode=0x" & Hex(RSA_KeyHashCode(strIntKey)) ' Unencrypted key strIntKey = rsaReadAnyPrivateKey("AlicePrivRSASign.pri", "") Debug.Print strIntKey Debug.Print "KeyHashCode=0x" & Hex(RSA_KeyHashCode(strIntKey)) ' Key in XML form strIntKey = rsaReadAnyPrivateKey("alice-pri.xml", "") Debug.Print strIntKey Debug.Print "KeyHashCode=0x" & Hex(RSA_KeyHashCode(strIntKey)) ``` ### See Also [RSA_ReadAnyPublicKey](#RSA_ReadAnyPublicKey) [[Contents](#topofpage)] [[Index](#index)] RSA_ReadAnyPublicKey ----------------------------------------------------- Reads from a file or string containing a public key into an "internal" public key string. ### VBA/VB6 Syntax `Public Declare Function RSA_ReadAnyPublicKey Lib "diCrPKI.dll" (ByVal strOutput As String, ByVal nOutChars As Long, ByVal strKeyFileOrString As String, ByVal nOptions As Long) As Long` `nRet = RSA_ReadAnyPublicKey(strOutput, nOutChars, strKeyFileOrString, nOptions) As Long` ### C/C++ Syntax `long __stdcall RSA_ReadAnyPublicKey(char *szOutput, long nOutChars, const char *szKeyFileOrString, long nOptions);` ### Parameters *szOutput* : [out] to receive encoded public key data in "internal" format. *nOutChars* : [in] specifying the maximum number of characters to be received. *szKeyFileOrString* : [in] specifying the name of file containing the key or a string containing the key in [PEM format](#pemstring) or XML format. *nOptions* : [in] not used in this release. Specify zero. ### Returns (VBA/C) If successful, the return value is the number of characters in or required for the output string; otherwise it returns a negative [error code](#errorcodes). ### VBA Wrapper Syntax Public Function [`rsaReadAnyPublicKey`](#VB_rsaReadAnyPublicKey) (szKeyFileOrString As String, Optional nOptions As Long = 0) As String ### .NET Equivalent [Rsa.ReadPublicKey Method](#M_Rsa_ReadPublicKey) ### C++ (STL) Equivalent static std::string [dipki::Rsa::ReadPublicKey](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rsa.html#a2d73a8d0f5c72a5c8328d290351bedb6 "External link") (const std::string &keyFileOrString) ### Python Equivalent static [Rsa.read_public_key](https://cryptosys.net/pki/pydocpki/class-stubs/Rsa.html#cryptosyspki.Rsa.read_public_key "External link")(keyfileorstr) ### Remarks For the "raw" VBA/C function, the user must allocate an output string buffer *szOutput* of the required length. Specify a zero *nOutChars* or an empty string for *szOutput* to find the required length. ANSI C users [must add one to this value](#cusersaddone) when allocating memory. This function will attempt to read the public key from "any" supported format. The output will be an ephemeral "internal" key string suitable for the current session only. Supported formats are: * X.509 certificate (.cer, .crt) file in either binary DER format or text PEM format * String containing the contents of an X.509 certificate file in base64 encoding * PKCS#1 RSA Public Key (.p1) file in either binary DER format or text PEM format * File containing X.509 SubjectPublicKeyInfo data (OpenSSL public key) in either binary DER format or text PEM format * String containing contents of any of the above files in text form as a [PEM string](#pemstring) * XML file or string containing an XKMS-conforming `RSAKeyValue` or `RSAKeyPair` element * JSON file or string containing a plaintext RSA public key represented in JSON Web Key (JWK) format. To read in a public key from a PFX/p12 file, use `[RSA_ReadAnyPrivateKey](#RSA_ReadAnyPrivateKey)` then `[RSA_PublicKeyFromPrivate](#RSA_PublicKeyFromPrivate)`. This supersedes the following functions: * `RSA_ReadPublicKey` * `RSA_GetPublicKeyFromCert` ### Example (VBA core function) This VB6/VBA wrapper function returns the "internal" public key string from the specified file. ``` Public Function rsaReadPublicKey(strKeyFile As String) As String ' Reads the public key from any supported public key file or PEM string ' Returns the key as an ephemeral base64 string or an empty string on error Dim nChars As Long ' How long is key string? nChars = RSA_ReadAnyPublicKey("", 0, strKeyFile, 0) If nChars <= 0 Then Exit Function End If ' Pre-dimension the string to receive data rsaReadPublicKey = String(nChars, " ") ' Read in the Public Key nChars = RSA_ReadAnyPublicKey(rsaReadPublicKey, nChars, strKeyFile, 0) End Function ``` This example reads in an RSA public key in JSON JWK format. ``` Dim strJson As String Dim strPublicKey As String Dim nChars As Long ' RSA public key as a JSON string ' Ref: RFC 7517 JSON Web Key (JWK) Appendix A.1 ' NB quotation marks (") inside a VBA string are escaped as "". strJson = "{""kty"":""RSA""," & _ """n"": ""0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx" & _ "4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMs" & _ "tn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2" & _ "QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbI" & _ "SD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqb" & _ "w0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw""," & _ """e"":""AQAB""," & _ """alg"":""RS256""," & _ """kid"":""2011-04-29""}" Debug.Print strJson ' Read in the public key as an internal string ' How many characters? nChars = RSA_ReadAnyPublicKey(ByVal 0&, 0, strJson, 0) Debug.Print "RSA_ReadAnyPublicKey returns " & nChars strPublicKey = String(nChars, " ") nChars = RSA_ReadAnyPublicKey(strPublicKey, nChars, strJson, 0) ' Examine the key's properties Debug.Print "RSA key size = " & RSA_KeyBits(strPublicKey) & " bits" Debug.Print "Hash code = 0x" & Hex(RSA_KeyHashCode(strPublicKey)) ``` ``` {"kty":"RSA","n": "0vx7agoebGcQSuuPiLJXZptN9nndr [cut] JzKnqDKgw","e":"AQAB","alg":"RS256","kid":"2011-04-29"} RSA_ReadAnyPublicKey returns 400 RSA key size = 2048 bits Hash code = 0xDFC04E17 ``` ### Example (VBA wrapper function) ``` Dim strIntKey As String strIntKey = rsaReadAnyPublicKey("AlicePubRSA.pub") Debug.Print strIntKey Debug.Print "KeyHashCode=0x" & Hex(RSA_KeyHashCode(strIntKey)) ' X.509 certificate strIntKey = rsaReadAnyPublicKey("AliceRSASignByCarl.cer") Debug.Print strIntKey Debug.Print "KeyHashCode=0x" & Hex(RSA_KeyHashCode(strIntKey)) ' Key in XML form strIntKey = rsaReadAnyPublicKey("alice-pub.xml") Debug.Print strIntKey Debug.Print "KeyHashCode=0x" & Hex(RSA_KeyHashCode(strIntKey)) ``` ### See Also [RSA_ReadAnyPublicKey](#RSA_ReadAnyPublicKey) [[Contents](#topofpage)] [[Index](#index)] RSA_ReadEncPrivateKey ------------------------------------------------------- Reads from an encrypted PKCS#8 private key info file into an "internal" private key string. *[Superseded by* `[RSA_ReadAnyPrivateKey](#RSA_ReadAnyPrivateKey)`.] ### VBA/VB6 Syntax `Public Declare Function RSA_ReadEncPrivateKey Lib "diCrPKI.dll" (ByVal strPrivateKey As String, ByVal nOutChars As Long, ByVal strEpkFileName As String, ByVal strPassword As String, ByVal nOptions As Long) As Long` `nRet = RSA_ReadEncPrivateKey(strPrivateKey, nOutChars, strEpkFileName, strPassword, nOptions) As Long` ### C/C++ Syntax `long __stdcall RSA_ReadEncPrivateKey(char *szOutput, long nOutChars, const char *szEpkFile, const char *szPassword, long nOptions);` ### Parameters *szOutput* : [out] to receive encoded private key data in "internal" format. *nOutChars* : [in] specifying the maximum number of characters to be received. *szEpkFile* : [in] specifying the filename of a PKCS-8 encrypted private key info file (or a string containing the key in [PEM format](#pemstring)). *szPassword* : [in] containing the password *nOptions* : [in] not used in this release. Specify zero. ### Returns (VBA/C) If successful, the return value is the number of characters in or required for the output string; otherwise it returns a negative [error code](#errorcodes). ### .NET Equivalent [Rsa.ReadEncPrivateKey Method](#M_Rsa_ReadEncPrivateKey) ### Remarks Only PKCS-8 `EncryptedPrivateKeyInfo` data using the `rsaEncryption` algorithm is supported. The file must be either in binary BER-encoded format or PEM format. ### See Also [RSA_SaveEncPrivateKey](#RSA_SaveEncPrivateKey) [RSA_ReadPrivateKeyInfo](#RSA_ReadPrivateKeyInfo) [RSA_SavePrivateKeyInfo](#RSA_SavePrivateKeyInfo) [RSA_GetPrivateKeyFromPFX](#RSA_GetPrivateKeyFromPFX) [[Contents](#topofpage)] [[Index](#index)] RSA_ReadPrivateKeyFromPFX --------------------------------------------------------------- Reads a private key directly from an encrypted PFX/PKCS-12 file into an "internal" private key string. *[Superseded by* `[RSA_ReadAnyPrivateKey](#RSA_ReadAnyPrivateKey)`.] ### VBA/VB6 Syntax `Public Declare Function RSA_ReadPrivateKeyFromPFX Lib "diCrPKI.dll" (ByVal strOutput As String, ByVal nOutChars As Long, ByVal strPfxFile As String, ByVal strPassword As String, ByVal nOptions As Long) As Long` `nRet = RSA_ReadPrivateKeyFromPFX(strOutput, nOutChars, strPfxFile, strPassword, nOptions) As Long` ### C/C++ Syntax `long __stdcall RSA_ReadPrivateKeyFromPFX(char *szOutput, long nOutChars, const char *szPfxFile, const char *szPassword, long nOptions);` ### Parameters *szOutput* : [out] to receive private key data in "internal" encoded format. *nOutChars* : [in] specifying the maximum number of characters to be received. *szPfxFile* : [in] containing the PFX filename (or a string containing the PFX data in [PEM format](#pemstring)) *szPassword* : [in] containing the password. *nOptions* : [in] option flags: not used in this release. Specify zero. ### Returns (VBA/C) If successful, the return value is the number of characters in or required for the output string; otherwise it returns a negative [error code](#errorcodes). ### .NET Equivalent [Rsa.ReadPrivateKeyFromPFX Method](#M_Rsa_ReadPrivateKeyFromPFX) ### Remarks This will read the private key from the first `pkcs8ShroudedKeyBag` object it finds and can decrypt in the PFX file. The result is a string in ["internal" key string format](#internalkeys) valid only for the current session. Call the function with an empty or NULL *szOutput* string or zero *nOutChars* parameter to find out the required length of the output string. C/C++ users should add one to this value when allocating memory. If you need the public key instead from a PFX file, then use this function followed by [`RSA_PublicKeyFromPrivate()`](#RSA_PublicKeyFromPrivate). If you just want to extract the encrypted private key and save directly as a pkcs-8 file, then use the [`RSA_GetPrivateKeyFromPFX()`](#RSA_GetPrivateKeyFromPFX) function. ### Example ``` Dim strPfxFile As String Dim strPrivateKey As String Dim strPassword As String Dim nChars As Long Dim nCode As Long Dim nRet As Long strPfxFile = "bob.pfx" strPassword = "password" ' Read private key from PFX file into internal string form nChars = RSA_ReadPrivateKeyFromPFX("", 0, strPfxFile, strPassword, 0) If nChars <= 0 Then Exit Sub ' Catch error here strPrivateKey = String(nChars, " ") nChars = RSA_ReadPrivateKeyFromPFX(strPrivateKey, Len(strPrivateKey), strPfxFile, strPassword, 0) ' Display some info about it Debug.Print "Private key length = " & RSA_KeyBits(strPrivateKey) & " bits" nCode = RSA_KeyHashCode(strPrivateKey) Debug.Print "KeyHashCode=" & Hex(nCode) nRet = RSA_CheckKey(strPrivateKey, 0) Debug.Print "RSA_CheckKey returns " & nRet & ": (PKI_VALID_PRIVATEKEY=" & PKI_VALID_PRIVATEKEY & ")" ' Clean up strPrivateKey = wipeString(strPrivateKey) strPassword = wipeString(strPassword) ``` ``` Private key length = 1024 bits KeyHashCode=6BCC120C RSA_CheckKey returns 0: (PKI_VALID_PRIVATEKEY=0) ``` ### See Also [RSA_GetPrivateKeyFromPFX](#RSA_GetPrivateKeyFromPFX) [RSA_ReadEncPrivateKey](#RSA_ReadEncPrivateKey) [RSA_PublicKeyFromPrivate](#RSA_PublicKeyFromPrivate) [[Contents](#topofpage)] [[Index](#index)] RSA_ReadPrivateKeyInfo --------------------------------------------------------- Reads from an (unencrypted) PKCS-8 private key info file into an "internal" private key string. *[Superseded by* `[RSA_ReadAnyPrivateKey](#RSA_ReadAnyPrivateKey)`.] ### VBA/VB6 Syntax `Public Declare Function RSA_ReadPrivateKeyInfo Lib "diCrPKI.dll" (ByVal strPrivateKey As String, ByVal nOutChars As Long, ByVal strPriFileName As String, ByVal nOptions As Long) As Long` `nRet = RSA_ReadPrivateKeyInfo(strPrivateKey, nOutChars, strPriFileName, nOptions) As Long` ### C/C++ Syntax `long __stdcall RSA_ReadPrivateKeyInfo(char *szOutput, long nOutChars, const char *szKeyFile, long nOptions);` ### Parameters *szOutput* : [out] to receive private key data in "internal" encoded format. *nOutChars* : [in] specifying the maximum number of characters to be received. *szKeyFile* : [in] specifying the filename of a `PrivateKeyInfo` file (or a string containing the key in [PEM format](#pemstring)). *nOptions* : [in] option flags: not used in this release. Specify zero. ### Returns (VBA/C) If successful, the return value is the number of characters in or required for the output string; otherwise it returns a negative [error code](#errorcodes). ### .NET Equivalent [Rsa.ReadPrivateKeyInfo Method](#M_Rsa_ReadPrivateKeyInfo) ### Remarks Only PKCS-8 `PrivateKeyInfo` files specifying the `rsaEncryption` algorithm are supported together with OpenSSL-compatible `RSA PRIVATE KEY` files. Files may be in either binary BER/DER-encoded format or PEM format. Call the function with an empty or NULL *szOutput* string or zero *nOutChars* parameter to find out the required length of the output string. C/C++ users should add one to this value when allocating memory. ### Example This example reads in Bob's unencrypted private key from the file `BobPrivRSAEncrypt.pri` from [[SMIME-EX]](#SMIME-EX) and saves in encrypted form using the password "password". The default PBE algorithm `pbeWithSHAAnd3-KeyTripleDES-CBC` is used with an iteration count of 1000. ``` Dim strPRIFile As String Dim strEPKFile As String Dim strPrivateKey As String Dim strPK1 As String Dim nKeyLen As String Dim nRet As Long ' Read in Bob's unencrypted PrivateKeyInfo data strPRIFile = "BobPrivRSAEncrypt.pri" nKeyLen = RSA_ReadPrivateKeyInfo("", 0, strPRIFile, 0) If nKeyLen <= 0 Then MsgBox "Failed to read Private Key file" Exit Sub End If strPrivateKey = String(nKeyLen, " ") nRet = RSA_ReadPrivateKeyInfo(strPrivateKey, nKeyLen, strPRIFile, 0) If nRet <= 0 Then MsgBox "Failed to read Private Key file" Exit Sub End If ' Now we save it with a password strEPKFile = "BobPrivRSAEncrypt.p8e" nRet = RSA_SaveEncPrivateKey(strEPKFile, strPrivateKey, 1000, "password", 0) Debug.Print "RSA_SaveEncPrivateKey returns " & nRet ' Check we can read it strPK1 = rsaReadPrivateKey(strEPKFile, "password") ' Sneak a look at the two key strings. ' CAUTION: _Never_ print these in a production system! Debug.Print strPK1 Debug.Print strPrivateKey ' To compare these strings, use the RSA_KeyHashCode function Debug.Print Hex(RSA_KeyHashCode(strPK1)) Debug.Print Hex(RSA_KeyHashCode(strPrivateKey)) If RSA_KeyHashCode(strPK1) = RSA_KeyHashCode(strPrivateKey) Then Debug.Print "Key string values match." Else Debug.Print "ERROR: key strings do not match." End If ``` ### See Also [RSA_ReadEncPrivateKey](#RSA_ReadEncPrivateKey) [RSA_KeyHashCode](#RSA_KeyHashCode) [[Contents](#topofpage)] [[Index](#index)] RSA_ReadPublicKey ----------------------------------------------- Reads from an RSA public key file into an "internal" public key string. *[Superseded by* `[RSA_ReadAnyPublicKey](#RSA_ReadAnyPublicKey)`.] ### VBA/VB6 Syntax `Public Declare Function RSA_ReadPublicKey Lib "diCrPKI.dll" (ByVal strPublicKey As String, ByVal nOutChars As Long, ByVal strKeyFileName As String, ByVal nOptions As Long) As Long` `nRet = RSA_ReadPublicKey(strPublicKey, nOutChars, strKeyFileName, nOptions) As Long` ### C/C++ Syntax `long __stdcall RSA_ReadPublicKey(char *szOutput, long nOutChars, const char *szPubKeyFile, long nOptions);` ### Parameters *szOutput* : [out] to receive public key data in encoded "internal" format. *nOutChars* : [in] specifying the maximum number of characters to be received. *szPubKeyFile* : [in] specifying the filename of a public key file (or a string containing the key in [PEM format](#pemstring)). *nOptions* : [in] option flags: not used in this release. Specify zero. ### Returns (VBA/C) If successful, the return value is the number of characters in or required for the output string; otherwise it returns a negative [error code](#errorcodes). ### VBA Wrapper Syntax Public Function [`rsaReadPublicKey`](#VB_rsaReadPublicKey) (szKeyFileOrString As String, Optional nOptions As Long = 0) As String ### .NET Equivalent [Rsa.ReadPublicKey Method](#M_Rsa_ReadPublicKey) ### Remarks Both PKCS-1 `RSAPublicKey` and OpenSSL `SubjectPublicKeyInfo` formats are supported. The file can be in binary BER-encoded format or PEM format, or be passed as a string containing the data in [PEM format](#pemstring). Call the function with an empty or NULL *szOutput* string or zero *nOutChars* parameter to find out the required length of the output string. C/C++ users should add one to this value when allocating memory. ### Example ### See Also [RSA_ReadAnyPublicKey](#RSA_ReadAnyPublicKey) [RSA_SavePublicKey](#RSA_SavePublicKey) [RSA_GetPublicKeyFromCert](#RSA_GetPublicKeyFromCert) [[Contents](#topofpage)] [[Index](#index)] RSA_SaveEncKey ----------------------------------------- Save an internal RSA key string to an encrypted key file. ### VBA/VB6 Syntax `Public Declare Function RSA_SaveEncKey Lib "diCrPKI.dll" (ByVal strFileOut As String, ByVal strIntKeyString As String, ByVal strPassword As String, ByVal strParams As String, ByVal nOptions As Long) As Long` `nRet = RSA_SaveEncKey(strFileOut, strIntKeyString, strPassword, strParams, nOptions) As Long` ### C/C++ Syntax `long __stdcall RSA_SaveEncKey(const char *szFileOut, const char *szIntKeyString, const char *szPassword, const char *szParams, long nOptions);` ### Parameters *szFileOut* : [in] Name of output file to be created. *szIntKeyString* : [in] The private RSA key as an internal key string. *szPassword* : [in] Password for encrypted private key (required). *szParams* : [in] Optional parameters. Set as the empty string `""` for defaults. Otherwise include a set of attribute-value pairs separated by a semi-colon ";" to set options from the following * `count=` to set the iteration count in the encrypted private key used in the PBKDF method, e.g. `"count=5000;"` [default=`2048`] * `prf=` to change the HMAC algorithm used in the PBKDF2 method, e.g. `"prf=hmacWithSHA256;"` [default=`hmacwithSHA1`] Valid values for hmac-name are `{hmacWithSHA1|hmacWithSHA224|hmacWithSHA256|hmacWithSHA384|hmacWithSHA512}`. *nOptions* : [in] option flags: to specify the PBE algorithm. Select one of: `PKI_PBE_SHA_3DES` (0) to use `pbeWithSHAAnd3-KeyTripleDES-CBC` from PKCS12 (default) `PKI_PBE_PBKDF2_DESEDE3` for PBKDF2 using `des-EDE3-CBC` `PKI_PBE_PBKDF2_AES128` for PBKDF2 using `aes128-CBC` `PKI_PBE_PBKDF2_AES192` for PBKDF2 using `aes192-CBC` `PKI_PBE_PBKDF2_AES256` for PBKDF2 using `aes256-CBC` (there are more options - see [security options for encrypted private keys](#encryptedkeyoptions)) and optionally add `PKI_KEY_FORMAT_PEM` to export an `ENCRYPTED PRIVATE KEY` PEM-format file (default is binary BER-encoded format). ### Returns (VBA/C) If successful, the return value is zero; otherwise it returns a nonzero [error code](#errorcodes). ### VBA Wrapper Syntax Public Function [`rsaSaveEncKey`](#VB_rsaSaveEncKey) (szOutputFile As String, szKeyStr As String, szPassword As String, Optional szParams As String = "", Optional nOptions As Long = 0) As Long ### .NET Equivalent [Rsa.SaveEncKey Method](#M_Rsa_SaveEncKey) ### C++ (STL) Equivalent static int [dipki::Rsa::SaveEncKey](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rsa.html#a444982f3c1f80e8971f464eac6f47a26 "External link") (const std::string &outputFile, const std::string &keyStr, const std::string &password, PbeScheme pbes=PbeScheme::Default, const std::string ¶mString="", Format fileFormat=Format::Binary) ### Python Equivalent static [Rsa.save_enc_key](https://cryptosys.net/pki/pydocpki/class-stubs/Rsa.html#cryptosyspki.Rsa.save_enc_key "External link")(outputfile, intkeystr, password, pbescheme=0, params='', fileformat=0) ### Remarks *[New in v20.3]* ### Example ### See Also [[Contents](#topofpage)] [[Index](#index)] RSA_SaveEncPrivateKey ------------------------------------------------------- Saves a private key string to a PKCS-8 encrypted private key info file. ### VBA/VB6 Syntax `Public Declare Function RSA_SaveEncPrivateKey Lib "diCrPKI.dll" (ByVal strOutputFile As String, ByVal strPrivateKey As String, ByVal nCount As Long, ByVal strPassword As String, ByVal nOptions As Long) As Long` `nRet = RSA_SaveEncPrivateKey(strOutputFile, strPrivateKey, nCount, strPassword, nOptions) As Long` ### C/C++ Syntax `long __stdcall RSA_SaveEncPrivateKey(const char *szFileOut, const char *szKeyString, long nCount, const char *szPassword, long nOptions);` ### Parameters *szFileOut* : [in] specifying the filename of the output file to be created. *szKeyString* : [in] containing the private key string *nCount* : [in] specifying the number of iterations to carry out *szPassword* : [in] containing the password *nOptions* : [in] option flags: to specify the PBE algorithm. Select one of: `PKI_PBE_SHA_3DES` (0) to use `pbeWithSHAAnd3-KeyTripleDES-CBC` (default) `PKI_PBE_PBKDF2_DESEDE3` for PBKDF2 using `des-EDE3-CBC` `PKI_PBE_PBKDF2_AES128` for PBKDF2 using `aes128-CBC` `PKI_PBE_PBKDF2_AES192` for PBKDF2 using `aes192-CBC` `PKI_PBE_PBKDF2_AES256` for PBKDF2 using `aes256-CBC` (there are more options - see [security options for encrypted private keys](#encryptedkeyoptions)) and optionally add `PKI_KEY_FORMAT_PEM` to export an `ENCRYPTED PRIVATE KEY` PEM-format file (default is binary BER-encoded format). ### Returns (VBA/C) If successful, the return value is zero; otherwise it returns a nonzero [error code](#errorcodes). ### .NET Equivalent [Rsa.SaveEncPrivateKey Method](#M_Rsa_SaveEncPrivateKey_StringStringInt32StringRsa_PbeOptionsRsa_Format) [Rsa.SaveEncPrivateKey Method](#M_Rsa_SaveEncPrivateKey_StringStringInt32StringCipherAlgorithmHashAlgorithmRsa_Format) ### Remarks The default is to save as a binary BER-encoded PKCS-8 EncryptedPrivateKeyInfo file. If the `PKI_KEY_FORMAT_PEM` option is added, the file be will in PEM format. The PEM encrypted private key format uses the header and footer lines: ``` -----BEGIN ENCRYPTED PRIVATE KEY----- -----END ENCRYPTED PRIVATE KEY----- ``` ### Example This example reads Carl's unencrypted private key info file from [[SMIME-EX]](#SMIME-EX) and saves in encrypted format with the password "password". It then checks that the two keys match by using the `[RSA_KeyHashCode](#RSA_KeyHashCode)` function. ``` Dim strPRIFile As String Dim strEPKFile As String Dim strPrivateKey As String Dim strPK1 As String Dim nChars As String Dim nRet As Long strPRIFile = "CarlPrivRSASign.pri" ' Read in Carl's unencrypted PrivateKeyInfo data nChars = RSA_ReadPrivateKeyInfo("", 0, strPRIFile, 0) If nChars <= 0 Then MsgBox "Failed to read Private Key file" Exit Sub End If ' Dimension the string to receive it - IMPORTANT strPrivateKey = String(nChars, " ") ' Read in as an "internal" key string nRet = RSA_ReadPrivateKeyInfo(strPrivateKey, nChars, strPRIFile, 0) If nRet <= 0 Then MsgBox "Failed to read Private Key file" Exit Sub End If Debug.Print "Private key length is " & RSA_KeyBits(strPrivateKey) & " bits" ' Now save it in PKCS#8 encrypted form with a password strEPKFile = "CarlPrivRSASign.p8e" nRet = RSA_SaveEncPrivateKey(strEPKFile, strPrivateKey, 1000, "password", 0) Debug.Print "RSA_SaveEncPrivateKey returns " & nRet & " (expected 0)" ' Check we can read it (note easier wrapper function) strPK1 = rsaReadPrivateKey(strEPKFile, "password") If Len(strPK1) > 0 Then Debug.Print "Encrypted private key is " & RSA_KeyBits(strPK1) & " bits" Else MsgBox "Unable to read encrypted private key" End If ' To compare these strings, use the RSA_KeyHashCode function Debug.Print "HashCode(original prikeyinfo) =" & Hex(RSA_KeyHashCode(strPrivateKey)) Debug.Print "HashCode(encrypted prikeyinfo)=" & Hex(RSA_KeyHashCode(strPK1)) If RSA_KeyHashCode(strPK1) = RSA_KeyHashCode(strPrivateKey) Then Debug.Print "OK, Key string values match." Else Debug.Print "ERROR: key strings do not match." End If ``` This should give the output ``` Private key length is 1024 bits RSA_SaveEncPrivateKey returns 0 (expected 0) Encrypted private key is 1024 bits HashCode(original prikeyinfo) =A937B1B5 HashCode(encrypted prikeyinfo)=A937B1B5 OK, Key string values match. ``` ### See Also [RSA_ReadEncPrivateKey](#RSA_ReadEncPrivateKey) [[Contents](#topofpage)] [[Index](#index)] RSA_SavePrivateKeyInfo --------------------------------------------------------- Saves a private key string to an (unencrypted) PKCS-8 private key info file. ### VBA/VB6 Syntax `Public Declare Function RSA_SavePrivateKeyInfo Lib "diCrPKI.dll" (ByVal strOutputFile As String, ByVal strPrivateKey As String, ByVal nOptions As Long) As Long` `nRet = RSA_SavePrivateKeyInfo(strOutputFile, strPrivateKey, nOptions) As Long` ### C/C++ Syntax `long __stdcall RSA_SavePrivateKeyInfo(const char *szFileOut, const char *szKeyString, long nOptions);` ### Parameters *szFileOut* : [in] specifying the filename of the output file to be created. *szKeyString* : [in] containing the private key string *nOptions* : [in] Option flags. Select one of: `PKI_DEFAULT` (0) to export a binary BER-encoded file (default) `PKI_KEY_FORMAT_PEM` to export a PEM-like `PRIVATE KEY` file `PKI_KEY_FORMAT_SSL` to export an OpenSSL-compatible `RSA PRIVATE KEY` PEM file and optionally add ### Returns (VBA/C) If successful, the return value is zero; otherwise it returns a nonzero [error code](#errorcodes). ### .NET Equivalent [Rsa.SavePrivateKeyInfo Method](#M_Rsa_SavePrivateKeyInfo) ### Python Equivalent static [Rsa.save_key](https://cryptosys.net/pki/pydocpki/class-stubs/Rsa.html#cryptosyspki.Rsa.save_key "External link")(outputfile, keystr, fileformat=0) ### Remarks **Caution:** this data is saved in unencrypted form. Do not use for a production key. Any existing file of the specified name will be overwritten without warning. Saves by default as a binary BER-encoded file compatible with the PKCS-8 PrivateKeyInfo format. The PEM key format saved with the `PKI_KEY_FORMAT_PEM` option uses the header and footer lines: ``` -----BEGIN PRIVATE KEY----- -----END PRIVATE KEY----- ``` The OpenSSL-compatible PEM key format saved with the `PKI_KEY_FORMAT_SSL` option uses the header and footer lines: ``` -----BEGIN RSA PRIVATE KEY----- -----END RSA PRIVATE KEY----- ``` and is compatible with the PKCS-1 RSAPrivateKey format. ### Example ``` Dim strEPKFile As String Dim strPRIFile As String Dim strPEMFile As String Dim strPassword As String Dim strPrivateKey As String Dim nRet As Long strEPKFile = "rsa508.p8e" strPRIFile = "rsa508.pri" strPEMFile = "rsa508.pem" strPassword = "password" ' Read in the deciphered private key string strPrivateKey = rsaReadPrivateKey(strEPKFile, strPassword) If Len(strPrivateKey) = 0 Then MsgBox "Unable to retrieve private key" Exit Function End If Debug.Print strPrivateKey ' Save as unencrypted PrivateKeyInfo file nRet = RSA_SavePrivateKeyInfo(strPRIFile, strPrivateKey, 0) Debug.Print "RSA_SavePrivateKeyInfo returns " & nRet ' Save as unencrypted PEM-format file nRet = RSA_SavePrivateKeyInfo(strPEMFile, strPrivateKey, PKI_KEY_FORMAT_PEM) Debug.Print "RSA_SavePrivateKeyInfo returns " & nRet ``` ### See Also [RSA_ReadPrivateKeyInfo](#RSA_ReadPrivateKeyInfo) [[Contents](#topofpage)] [[Index](#index)] RSA_SavePublicKey ----------------------------------------------- Saves a public key string to PKCS-1 public key file. ### VBA/VB6 Syntax `Public Declare Function RSA_SavePublicKey Lib "diCrPKI.dll" (ByVal strOutputFile As String, ByVal strPublicKey As String, ByVal nOptions As Long) As Long` `nRet = RSA_SavePublicKey(strOutputFile, strPublicKey, nOptions) As Long` ### C/C++ Syntax `long __stdcall RSA_SavePublicKey(const char *szFileOut, const char *szKeyString, long nOptions);` ### Parameters *szFileOut* : [in] specifying the filename of the output file to be created. *szKeyString* : [in] containing the public key string (or a private key string) *nOptions* : [in] Option flags. Select one of: `PKI_DEFAULT` (0) to export a binary DER/BER-encoded file (default) `PKI_KEY_FORMAT_PEM` to export a PEM-like `"RSA PUBLIC KEY"` file `PKI_KEY_FORMAT_SSL` to export an OpenSSL-compatible `"PUBLIC KEY"` PEM file ### Returns (VBA/C) If successful, the return value is zero; otherwise it returns a nonzero [error code](#errorcodes). ### VBA Wrapper Syntax Public Function [`rsaSaveKey`](#VB_rsaSaveKey) (szOutputFile As String, szKeyStr As String, Optional nOptions As Long = 0) As Long ### .NET Equivalent [Rsa.SavePublicKey Method](#M_Rsa_SavePublicKey) ### C++ (STL) Equivalent static int [dipki::Rsa::SaveKey](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rsa.html#a2ce90bf0f13cbb2098a34b838f7f1af2 "External link") (const std::string &outputFile, const std::string &keyStr, Format fileFormat=Format::Binary) ### Remarks Any existing file of the specified name will be overwritten without warning. Saves by default as binary DER/BER-encoded PKCS-1 RSAPublicKey data. The file saved with the `PKI_KEY_FORMAT_PEM` option is the same data in PEM format with header and footer lines: ``` -----BEGIN RSA PUBLIC KEY----- -----END RSA PUBLIC KEY----- ``` The file saved with the `PKI_KEY_FORMAT_SSL` option is compatible with the format used by OpenSSL. The data is saved as X.509 SubjectPublicKeyInfo format encoded with header and footer lines: ``` -----BEGIN PUBLIC KEY----- -----END PUBLIC KEY----- ``` The OpenSSL format key is saved with "Unix" line endings and a line length of strictly 64 characters. You can use this function to extract a public key from a private key. Just pass the internal private key string instead of the public key string. ### Example See the example in [`RSA_GetPublicKeyFromCert`](#RSA_GetPublicKeyFromCert). ### See Also [RSA_ReadPublicKey](#RSA_ReadPublicKey) [RSA_GetPublicKeyFromCert](#RSA_GetPublicKeyFromCert) [[Contents](#topofpage)] [[Index](#index)] RSA_ToXMLString ------------------------------------------- Creates an XML string representation of an RSA internal key string. ### VBA/VB6 Syntax `Public Declare Function RSA_ToXMLString Lib "diCrPKI.dll" (ByVal strOutput As String, ByVal nOutChars As Long, ByVal strKeyString As String, ByVal nOptions As Long) As Long` `nRet = RSA_ToXMLString(strOutput, nOutChars, strKeyString, nOptions) As Long` ### C/C++ Syntax `long __stdcall RSA_ToXMLString(char *szOutput, long nOutChars, const char *szKeyString, long nOptions);` ### Parameters *szOutput* : [out] to receive XML data. *nOutChars* : [in] specifying the maximum number of characters to be received. *szKeyString* : [in] containing the RSA public or private key in internal format *nOptions* : [in] option flags: Select and combine: `PKI_DEFAULT` (0) to output in appropriate W3C standard format (`RSAKeyValue` for public key and `RSAKeyPair` for private key) `PKI_XML_RSAKEYVALUE` to force private key output as .NET-compatible `RSAKeyValue` format (instead of W3C `RSAKeyPair`) `PKI_XML_EXCLPRIVATE` to exclude the private key (use to get a public key `RSAKeyValue` from a private key) `PKI_XML_HEXBINARY` to output with data in non-conforming `hexBinary` format ### Returns (VBA/C) If successful, the return value is the number of characters in or required for the output string; otherwise it returns a negative [error code](#errorcodes). ### VBA Wrapper Syntax Public Function [`rsaToXMLString`](#VB_rsaToXMLString) (szKeyString As String, Optional nOptions As Long = 0) As String ### .NET Equivalent [Rsa.ToXMLString Method (String, Rsa.XmlOptions)](#M_Rsa_ToXMLString_StringRsa_XmlOptions) ### C++ (STL) Equivalent static std::string [dipki::Rsa::ToXMLString](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rsa.html#a33afa8224f6a3d5a3142eddb9e223b70 "External link") (const std::string &keyStr, XmlOptions opts=XmlOptions::None, const std::string &prefix="") ### Remarks For the "raw" VBA/C function, the user must allocate an output string buffer *szOutput* of the required length. Specify a zero *nOutChars* or an empty string for *szOutput* to find the required length. ANSI C users [must add one to this value](#cusersaddone) when allocating memory. **Caution:** the private key is saved in unencrypted form. Do not use for a production key. Both public and private key data can be output. The key must have been read first into an internal key string using one of the other RSA key input functions in this toolkit. If the internal key is a public key, or if the `PKI_XML_EXCLPRIVATE` option is used with a private key, the output will always be a `RSAKeyValue` element containing just `` and `` elements as per [[XMLDSIG](#XMLDSIG)]. If the internal key is a private key and the `PKI_XML_EXCLPRIVATE` option is *not* used, the default output will be a a [XKMS](#XKMS)-conforming `RSAKeyPair` element with the private key parameters included. Including the `PKI_XML_RSAKEYVALUE` option will force a .NET-compatible `RSAKeyValue` element instead. The only difference between `RSAKeyPair` and `RSAKeyValue` is in the name of the outer XML element. The default behaviour is to comply with the W3C standards [[XKMS](#XKMS)] and [[XMLDSIG](#XMLDSIG)]. Users who wish to export a private key to use in the .NET world will probably want to use the `PKI_XML_RSAKEYVALUE` option. The `PKI_XML_HEXBINARY` option will output the binary data in `hexBinary` encoding format instead of base64. This latter format is not in conformance with any W3C standard, but is provided to allow users to see the data in more readable hex format. Such a format can be read by this toolkit's [`RSA_FromXMLString()`](#RSA_FromXMLString) function, but don't try using it anywhere else. ### Example (VBA core function) This example reads in a private key from a encrypted private key file and then converts to an XML string in the .NET-compatible format. ``` Dim strEPKFile As String Dim strPassword As String Dim strPrivateKey As String Dim strXML As String Dim nLen As Long strEPKFile = "AlicePrivRSASign.p8e" strPassword = "password" ' Read in the deciphered private key string in our internal format strPrivateKey = rsaReadPrivateKey(strEPKFile, strPassword) If Len(strPrivateKey) = 0 Then MsgBox "Unable to retrieve private key" Exit Function End If Debug.Print "INTKEY=" & strPrivateKey ' Convert to XML nLen = RSA_ToXMLString("", 0, strPrivateKey, PKI_XML_RSAKEYVALUE) ' pre-dimension first strXML = String(nLen, " ") nLen = RSA_ToXMLString(strXML, Len(strXML), strPrivateKey, PKI_XML_RSAKEYVALUE) strXML = Left(strXML, nLen) Debug.Print "XML=" & strXML ``` The output should look like this (only longer): ``` INTKEY=MIICXAIBAAKBgQDgiXM5jdj19eiHdjl/ ... XML=4IlzOY3Y9fXoh ... +yRRKt/IQ== ``` ### Example (VBA wrapper function) ``` Dim strPrivateKey As String strPrivateKey = rsaReadPrivateKey("AlicePrivRSASign.p8e", "password") Debug.Print rsaToXMLString(strPrivateKey, 0) Debug.Print rsaToXMLString(strPrivateKey, PKI_XML_EXCLPRIVATE Or PKI_XML_HEXBINARY) Debug.Print rsaToXMLStringEx(strPrivateKey, "ds", PKI_XML_EXCLPRIVATE) ' Now derive internal private key string from XML Dim strXML As String Dim strKey As String strXML = rsaToXMLString(strPrivateKey) strKey = rsaFromXMLString(strXML) Debug.Print "Key length = " & RSA_KeyBits(strKey) & " bits" ``` ### See Also [RSA_FromXMLString](#RSA_FromXMLString) [[Contents](#topofpage)] [[Index](#index)] RSA_ToXMLStringEx ----------------------------------------------- Creates an XML string representation of an RSA internal key string with option to add a namespace prefix. ### VBA/VB6 Syntax `Public Declare Function RSA_ToXMLStringEx Lib "diCrPKI.dll" (ByVal strOutput As String, ByVal nOutChars As Long, ByVal strKeyString As String, ByVal strPrefix As String, ByVal nOptions As Long) As Long` `nRet = RSA_ToXMLStringEx(strOutput, nOutChars, strKeyString, "ds", nOptions) As Long` ### C/C++ Syntax `long __stdcall RSA_ToXMLStringEx(char *szOutput, long nOutChars, const char *szKeyString, const char *szPrefix, long nOptions);` ### Parameters *szOutput* : [out] to receive XML data. *nOutChars* : [in] specifying the maximum number of characters to be received. *szKeyString* : [in] containing the RSA public or private key in internal format *szPrefix* : [in] the namespace prefix to be added to all elements *nOptions* : [in] option flags: Select and combine: `PKI_DEFAULT` (0) to output in appropriate W3C standard format (`RSAKeyValue` for public key and `RSAKeyPair` for private key) `PKI_XML_RSAKEYVALUE` to force private key output as .NET-compatible `RSAKeyValue` format (instead of W3C `RSAKeyPair`) `PKI_XML_EXCLPRIVATE` to exclude the private key (use to get a public key `RSAKeyValue` from a private key) `PKI_XML_HEXBINARY` to output with data in non-conforming `hexBinary` format ### Returns (VBA/C) If successful, the return value is the number of characters in or required for the output string; otherwise it returns a negative [error code](#errorcodes). ### VBA Wrapper Syntax Public Function [`rsaToXMLStringEx`](#VB_rsaToXMLStringEx) (szKeyString As String, szPrefix As String, Optional nOptions As Long = 0) As String ### .NET Equivalent [Rsa.ToXMLString Method (String, String, Rsa.XmlOptions)](#M_Rsa_ToXMLString_StringStringRsa_XmlOptions) ### Python Equivalent static [Rsa.to_xmlstring](https://cryptosys.net/pki/pydocpki/class-stubs/Rsa.html#cryptosyspki.Rsa.to_xmlstring "External link")(keystr, opts=0, prefix='') ### Remarks For the "raw" VBA/C function, the user must allocate an output string buffer *szOutput* of the required length. Specify a zero *nOutChars* or an empty string for *szOutput* to find the required length. ANSI C users [must add one to this value](#cusersaddone) when allocating memory. Use this extended function to add a namespace prefix to all elements in the XML output; for example, ``. Note that it's up to the user to map the prefix to a URI somewhere in the final XML document (for reference, the correct form is `xmlns:ds="http://www.w3.org/2000/09/xmldsig#"`). See also the remarks for [RSA_ToXMLString](#RSA_ToXMLString). ### Example (VBA core function) ``` nLen = RSA_ToXMLStringEx("", 0, strPrivateKey, "ds", PKI_XML_EXCLPRIVATE) ' pre-dimension first strXML = String(nLen, " ") nLen = RSA_ToXMLStringEx(strXML, Len(strXML), strPrivateKey, "ds", PKI_XML_EXCLPRIVATE) strXML = Left(strXML, nLen) Debug.Print "XML=" & strXML ``` ``` uV3GoY7...Yb+F3Q==AQAB ``` ### Example (VBA wrapper function) ``` Dim strPrivateKey As String strPrivateKey = rsaReadPrivateKey("AlicePrivRSASign.p8e", "password") Debug.Print rsaToXMLString(strPrivateKey, 0) Debug.Print rsaToXMLString(strPrivateKey, PKI_XML_EXCLPRIVATE Or PKI_XML_HEXBINARY) Debug.Print rsaToXMLStringEx(strPrivateKey, "ds", PKI_XML_EXCLPRIVATE) ' Now derive internal private key string from XML Dim strXML As String Dim strKey As String strXML = rsaToXMLString(strPrivateKey) strKey = rsaFromXMLString(strXML) Debug.Print "Key length = " & RSA_KeyBits(strKey) & " bits" ``` ### See Also [RSA_ToXMLString](#RSA_ToXMLString) [[Contents](#topofpage)] [[Index](#index)] SIG_SignData ------------------------------------- Compute a signature value over data in a byte array. ### VBA/VB6 Syntax `Public Declare Function SIG_SignData Lib "diCrPKI.dll" (ByVal strOutput As String, ByVal nOutChars As Long, ByRef lpData As Byte, ByVal nDataLen As Long, ByVal strKeyFile As String, ByVal strPassword As String, ByVal strAlgName As String, ByVal nOptions As Long) As Long` `nRet = SIG_SignData(strOutput, nOutChars, lpData(0), nDataLen, strKeyFile, strPassword, strAlgName, nOptions)` ### C/C++ Syntax `long __stdcall SIG_SignData(char *szOutput, long nOutChars, const unsigned char *lpData, long nDataLen, const char *szKeyFile, const char *szPassword, const char *szAlgName, long nOptions);` ### Parameters *szOutput* : [out] string of sufficient length to receive the output. *nOutChars* : [in] specifying the maximum number of characters to be received. *lpData* : [in] byte array containing the input data to be signed. *nDataLen* : [in] specifying the length of the input data in bytes. *szKeyFile* : [in] specifying the name of the private key file (or a string containing the key in [PEM format](#pemstring), or a valid internal private key string). *szPassword* : [in] containing the password for the private key, or `""` if not required. *szAlgName* : [in] specifying the signature algorithm (case insensitive): `"sha1WithRSAEncryption"` (default - CAUTION) `"sha224WithRSAEncryption"` `"sha256WithRSAEncryption"` [minimum recommended] `"sha384WithRSAEncryption"` `"sha512WithRSAEncryption"` `"md5WithRSAEncryption"` [for legacy applications - not recommended for new implementations] `"ecdsaWithSHA1"` `"ecdsaWithSHA224"` `"ecdsaWithSHA256"` `"ecdsaWithSHA384"` `"ecdsaWithSHA512"` `"RSA-PSS-SHA1"` `"RSA-PSS-SHA224"` `"RSA-PSS-SHA256"` `"RSA-PSS-SHA384"` `"RSA-PSS-SHA512"` `"Ed25519"` *[New in v20.0]* (see Remarks) `"Ed448"` *[New in v22.0]* (see Remarks) or `""` to use the signature algorithm flag in *nOptions*, see [Specifying the signature algorithm in a SIG_ function](#sigalgorithm). *nOptions* : [in] Zero (0) for defaults. Add the bitflag: * `PKI_SIG_USEDIGEST` to pass the digest value of the data-to-be-signed as a byte array in the *lpData* parameter instead of the data itself (except with Ed25519). To change the format of the output (default base64 encoded), add one of: * `PKI_ENCODE_BASE64URL` to encode the output in the [URL-safe "base64url"](#base64url) encoding of [[RFC4648](#RFC4648)]; or * `PKI_ENCODE_HEX` to encode the output in hexadecimal (base16) encoding Options for ECDSA signatures only: * `PKI_SIG_DETERMINISTIC` to use the deterministic digital signature generation procedure of [[RFC6979](#RFC6979)] for ECDSA signatures (default=random k) * `PKI_SIG_ASN1DER` to form the signature value as a DER-encoded ASN.1 structure (as used by Bitcoin); (default=simple concatenation `r||s`) Options for RSA-PSS signatures only: *[New in v12.0]* (see [RSA signature and encryption schemes](#rsaschemes)) Add one of the following to specify the salt length: * `PKI_PSS_SALTLEN_HLEN` (0) to set the salt length to `hLen`, the length of the output of the hash function (default). * `PKI_PSS_SALTLEN_MAX` to set the salt length to the maximum possible (OpenSSL does this by default) * `PKI_PSS_SALTLEN_20` to set the salt length to be exactly 20 bytes regardless of the hash algorithm * `PKI_PSS_SALTLEN_ZERO` to set the salt length to be zero and, optionally, add:- * `PKI_MGF_MGF1SHA1` to force the MGF hash function to be SHA-1 (default = same as signature hash algorithm) ### Returns (VBA/C) If successful, the return value is the number of characters in or required for the output string; otherwise it returns a negative [error code](#errorcodes). ### VBA Wrapper Syntax Public Function [`sigSignData`](#VB_sigSignData) (lpData() As Byte, szKeyFile As String, szPassword As String, szAlgName As String, Optional nOptions As Long = 0) As String ### .NET Equivalent [Sig.SignData Method](#M_Sig_SignData) [Sig.SignDigest Method](#M_Sig_SignDigest) ### C++ (STL) Equivalent static std::string [dipki::Sig::SignData](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_sig.html#a782ee97d4d716ecdc933e4bc1c9ec36c "External link") (const bvec_t &data, const std::string &keyFileOrString, const std::string &password="", Alg alg=Alg::Default, Encoding encoding=Encoding::Base64, SigOptions opts=SigOptions::None) static [Sig.sign_digest](https://cryptosys.net/pki/pydocpki/class-stubs/Sig.html#cryptosyspki.Sig.sign_digest "External link")(digest, keyfile, password, alg, opts=Opts.DEFAULT, encoding=Encoding.DEFAULT) ### Python Equivalent `static [Sig.sign_data](https://cryptosys.net/pki/pydocpki/class-stubs/Sig.html#cryptosyspki.Sig.sign_data "External link")(data, keyfile, password, alg, opts=Opts.DEFAULT, encoding=Encoding.DEFAULT)` static [Sig.sign_digest](https://cryptosys.net/pki/pydocpki/class-stubs/Sig.html#cryptosyspki.Sig.sign_digest "External link")(digest, keyfile, password, alg, opts=Opts.DEFAULT, encoding=Encoding.DEFAULT) ### Remarks For the "raw" VBA/C function, the user must allocate an output string buffer *szOutput* of the required length. Specify a zero *nOutChars* or an empty string for *szOutput* to find the required length. ANSI C users [must add one to this value](#cusersaddone) when allocating memory. Computes the signature value over the input data (or its digest value) using the private key provided. The default output is a continuous string of base64 characters suitable to include in the `` node of an [XML-DSIG](#XMLDSIG) document. Alternative output encodings (base64url and hex) can be specified using the `PKI_ENCODE_` options. The `PKI_SIG_USEDIGEST` option cannot be used with Ed25519 or Ed448. The data to be signed must be passed *in toto* to the signature function. All options except the `PKI_ENCODE_` options are ignored for the Ed25519 and Ed448 algorithms. ### Example (VBA core function) ``` Dim strSignature As String Dim nChars As Long Dim strData As String Dim abData() As Byte Dim nDataLen As Long Dim strKeyFile As String Dim strPassword As String Dim strAlgName As String ' 1) Input data = three-character ASCII string "abc" strData = "abc" strKeyFile = "AlicePrivRSASign.p8e" strPassword = "password" ' CAUTION: do not hard-code passwords! strAlgName = "sha1WithRSAEncryption" ' Convert ASCII string to byte array abData = StrConv(strData, vbFromUnicode) nDataLen = Len(strData) ' Find required length of output string nChars = SIG_SignData("", 0, abData(0), nDataLen, strKeyFile, strPassword, _ strAlgName, 0) Debug.Print "SIG_SignData returns " & nChars & " (expected >0)" ' Allocate memory for output string strSignature = String(nChars, " ") nChars = SIG_SignData(strSignature, Len(strSignature), abData(0), nDataLen, _ strKeyFile, strPassword, strAlgName, 0) ' Output base64 signature value Debug.Print "SIG=" & strSignature ' 2) Use digest value instead of original data ' Convert known value of SHA-1("abc") in hex to an array of bytes abData = cnvBytesFromHexStr("a9993e364706816aba3e25717850c26c9cd0d89d") nDataLen = PKI_SHA1_BYTES ' Find required length of output string nChars = SIG_SignData("", 0, abData(0), nDataLen, strKeyFile, strPassword, _ strAlgName, PKI_SIG_USEDIGEST) Debug.Print "SIG_SignData returns " & nChars & " (expected >0)" ' Allocate memory for output string strSignature = String(nChars, " ") nChars = SIG_SignData(strSignature, Len(strSignature), abData(0), nDataLen, _ strKeyFile, strPassword, strAlgName, PKI_SIG_USEDIGEST) ' Output base64 signature value Debug.Print "SIG=" & strSignature ``` This uses Alice's encrypted private key to sign the ASCII string `"abc"` using both the original string data (converted to a byte array) and its digest value. The output should be ``` SIG_SignData returns 172 (expected >0) SIG=YK1aePtKQDDsVCyJdM0V9VOE6DZVTO3Z ... AmHH6QIsDZ8R8= SIG_SignData returns 172 (expected >0) SIG=YK1aePtKQDDsVCyJdM0V9VOE6DZVTO3Z ... AmHH6QIsDZ8R8= ``` The following example uses an elliptic curve key to produce an ECDSA signature in hex form using the "Deterministic" algorithm from [[RFC6979](#RFC6979)] ``` Dim nChars As Long Dim nBits As Long Dim strIntKey As String Dim strHexKey As String Dim strCurveName As String Dim strSignature As String Dim strData As String Dim abData() As Byte Dim nDataLen As Long Dim strAlgName As String ' Ref: [RFC6979] "Deterministic Usage of the DSA and ECDSA" ' A.2.3. ECDSA, 192 Bits (Prime Field) ' 1. READ IN PRIVATE KEY IN (HEX,CURVENAME) FORMAT strHexKey = "6FAB034934E4C0FC9AE67F5B5659A9D7D1FEFD187EE09FD4" strCurveName = "P-192" Debug.Print "KEYHEX: " & strHexKey Debug.Print "CURVE: " & strCurveName ' Find required length of internal key string nChars = ECC_ReadKeyByCurve("", 0, strHexKey, strCurveName, 0) Debug.Print "ECC_ReadKeyByCurve returns " & nChars & " (expected +ve)" ' Dimension the string to receive output strIntKey = String(nChars, " ") ' Read into internal key string nChars = ECC_ReadKeyByCurve(strIntKey, Len(strIntKey), strHexKey, strCurveName, 0) 'Debug.Print "INTKEY: " & strIntKey ' Check we got the bitlength we expected nBits = ECC_QueryKey("", 0, strIntKey, "keyBits", 0) Debug.Print "NBITS=" & nBits ' 2. PREPARE INPUT DATA AS AN ARRAY OF BYTES strData = "test" strAlgName = "ecdsaWithSHA1" ' Convert ASCII string to byte array abData = StrConv(strData, vbFromUnicode) nDataLen = Len(strData) '3. SIGN IT USING DETERMINISTIC ALGORITHM FROM [RFC6979] ' Find required length of output string nChars = SIG_SignData("", 0, _ abData(0), nDataLen, strIntKey, "", _ strAlgName, PKI_SIG_DETERMINISTIC Or PKI_ENCODE_HEX) Debug.Print "SIG_SignData returns " & nChars & " (expected >0)" ' Allocate memory for output string strSignature = String(nChars, " ") nChars = SIG_SignData(strSignature, Len(strSignature), _ abData(0), nDataLen, strIntKey, "", _ strAlgName, PKI_SIG_DETERMINISTIC Or PKI_ENCODE_HEX) ' Output hex signature value Debug.Print "SIG=" & strSignature ``` ``` KEYHEX: 6FAB034934E4C0FC9AE67F5B5659A9D7D1FEFD187EE09FD4 CURVE: P-192 ECC_ReadKeyByCurve returns 164 (expected +ve) NBITS=192 SIG_SignData returns 96 (expected >0) SIG=0f2141a0ebbc44d2e1af90a50ebcfce5e197b3b7d4de036deb18bc9e1f3d7387500cb99cf5f7c157070a8961e38700b7 ``` ### Example (VBA wrapper function) ``` Dim lpData() As Byte Dim strSig As String lpData = StrConv("abc", vbFromUnicode) strSig = sigSignData(lpData, "AlicePrivRSASign.p8e", "password", "sha1WithRSAEncryption") Debug.Print "SIG=" & strSig Debug.Print "OK =" & "YK1aePtKQDDsVCyJdM0V9VOE6DZVTO3Z ... AmHH6QIsDZ8R8=" ``` ### See Also [SIG_SignFile](#SIG_SignFile) [[Contents](#topofpage)] [[Index](#index)] SIG_SignFile ------------------------------------- Compute a signature value over data in a file. ### VBA/VB6 Syntax `Public Declare Function SIG_SignFile Lib "diCrPKI.dll" (ByVal strOutput As String, ByVal nOutChars As Long, ByVal strDataFile As String, ByVal strKeyFile As String, ByVal strPassword As String, ByVal strAlgName As String, ByVal nOptions As Long) As Long` `nRet = SIG_SignFile(strOutput, nOutChars, strDataFile, strKeyFile, strPassword, strAlgName, nOptions)` ### C/C++ Syntax `long __stdcall SIG_SignFile(char *szOutput, long nOutChars, const char *szDataFile, const char *szKeyFile, const char *szPassword, const char *szAlgName, long nOptions);` ### Parameters *szOutput* : [out] string of sufficient length to receive the output. *nOutChars* : [in] specifying the maximum number of characters to be received. *szDataFile* : [in] specifying the file containing the input data to be signed. *szKeyFile* : [in] specifying the name of the private key file (or a string containing the key in [PEM format](#pemstring), or a valid internal private key string). *szPassword* : [in] containing the password for the private key, or `""` if not required. *szAlgName* : [in] specifying the signature algorithm (case insensitive): `"sha1WithRSAEncryption"` (default - CAUTION) `"sha224WithRSAEncryption"` `"sha256WithRSAEncryption"` [minimum recommended] `"sha384WithRSAEncryption"` `"sha512WithRSAEncryption"` `"md5WithRSAEncryption"` [for legacy applications - not recommended for new implementations] `"ecdsaWithSHA1"` `"ecdsaWithSHA224"` `"ecdsaWithSHA256"` `"ecdsaWithSHA384"` `"ecdsaWithSHA512"` `"RSA-PSS-SHA1"` `"RSA-PSS-SHA224"` `"RSA-PSS-SHA256"` `"RSA-PSS-SHA384"` `"RSA-PSS-SHA512"` (Note that `Ed25519` and `Ed448` are not available with this function - see Remarks) or `""` to use the signature algorithm flag in *nOptions*, see [Specifying the signature algorithm in a SIG_ function](#sigalgorithm). *nOptions* : [in] Zero (0) for defaults. To change the format of the output (default base64 encoded), add one of: * `PKI_ENCODE_BASE64URL` to encode the output in the [URL-safe "base64url"](#base64url) encoding of [[RFC4648](#RFC4648)]; or * `PKI_ENCODE_HEX` to encode the output in hexadecimal (base16) encoding Options for ECDSA signatures only: * `PKI_SIG_DETERMINISTIC` to use the deterministic digital signature generation procedure of [[RFC6979](#RFC6979)] for ECDSA signatures (default=random k) * `PKI_SIG_ASN1DER` to form the signature value as a DER-encoded ASN.1 structure (as used by Bitcoin); (default=simple concatenation `r||s`) Options for RSA-PSS signatures only: *[New in v12.0]* (see [RSA signature and encryption schemes](#rsaschemes)) Add one of the following to specify the salt length: * `PKI_PSS_SALTLEN_HLEN` (0) to set the salt length to `hLen`, the length of the output of the hash function (default). * `PKI_PSS_SALTLEN_MAX` to set the salt length to the maximum possible (OpenSSL does this by default) * `PKI_PSS_SALTLEN_20` to set the salt length to be exactly 20 bytes regardless of the hash algorithm * `PKI_PSS_SALTLEN_ZERO` to set the salt length to be zero ### Returns (VBA/C) If successful, the return value is the number of characters in or required for the output string; otherwise it returns a negative [error code](#errorcodes). ### VBA Wrapper Syntax Public Function [`sigSignFile`](#VB_sigSignFile) (szDataFile As String, szKeyFile As String, szPassword As String, szAlgName As String, Optional nOptions As Long = 0) As String ### .NET Equivalent [Sig.SignFile Method](#M_Sig_SignFile) ### C++ (STL) Equivalent static std::string [dipki::Sig::SignFile](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_sig.html#aa011b65674d1c69b7ca1aafbb67fd0e0 "External link") (const std::string &dataFile, const std::string &keyFileOrString, const std::string &password="", Alg alg=Alg::Default, Encoding encoding=Encoding::Base64, SigOptions opts=SigOptions::None) ### Python Equivalent static [Sig.sign_file](https://cryptosys.net/pki/pydocpki/class-stubs/Sig.html#cryptosyspki.Sig.sign_file "External link")(datafile, keyfile, password, alg, opts=Opts.DEFAULT, encoding=Encoding.DEFAULT) ### Remarks For the "raw" VBA/C function, the user must allocate an output string buffer *szOutput* of the required length. Specify a zero *nOutChars* or an empty string for *szOutput* to find the required length. ANSI C users [must add one to this value](#cusersaddone) when allocating memory. This function is identical to `[SIG_SignData](#SIG_SignData)` except the data to be signed is in a file. The Ed25519 and Ed448 signature algorithms are not available with this function. To sign using Ed25519 or Ed448, read in the file to a byte array and use [SIG_SignData](#SIG_SignData). ### Example (VBA core function) ``` Dim strSignature As String Dim strDataFile As String Dim strKeyFile As String Dim strPassword As String Dim nChars As Long Dim nOption As Long 'Input data = file containing the three bytes 'a', 'b', 'c' strDataFile = "abc.txt" strKeyFile = "AlicePrivRSASign.p8e" strPassword = "password" ' CAUTION: do not hard-code passwords! nOption = PKI_SIG_SHA256RSA ' Use option instead of string ' Find required length of output string nChars = SIG_SignFile("", 0, strDataFile, strKeyFile, strPassword, "", nOption) Debug.Print "SIG_SignFile returns " & nChars & " (expected >0)" ' Allocate memory for output string strSignature = String(nChars, " ") nChars = SIG_SignFile(strSignature, Len(strSignature), strDataFile, strKeyFile, strPassword, "", nOption) ' Output base64 signature value Debug.Print "SIG=" & strSignature ``` This uses Alice's encrypted private key to sign a file using sha256WithRSAEncryption. The output should be ``` SIG_SignFile returns 172 (expected >0) SIG=tLy6hJadL4w9JI/A/qLCG0V...peD1VHSzgu/qirjOaA= ``` ### Example (VBA wrapper function) ``` Dim strSig As String strSig = sigSignFile("abc.txt", "AlicePrivRSASign.p8e", "password", "", PKI_SIG_SHA256RSA) Debug.Print "SIG=" & strSig Debug.Print "OK =" & "tLy6hJadL4w9JI/A/qLCG0V...peD1VHSzgu/qirjOaA=" ``` ### See Also [SIG_SignData](#SIG_SignData) [[Contents](#topofpage)] [[Index](#index)] SIG_VerifyData ----------------------------------------- Verify a signature value over data in a byte array. ### VBA/VB6 Syntax `Public Declare Function SIG_VerifyData Lib "diCrPKI.dll" (ByVal strSignature As String, ByRef lpData As Byte, ByVal nDataLen As Long, ByVal strCertOrKeyFile As String, ByVal strAlgName As String, ByVal nOptions As Long) As Long` `nRet = SIG_VerifyData(strSignature, lpData(0), nDataLen, strCertOrKeyFile, strAlgName, nOptions)` ### C/C++ Syntax `long __stdcall SIG_VerifyData(const char *szSignature, const unsigned char *lpData, long nDataLen, const char *szCertOrKeyFile, const char *szAlgName, long nOptions);` ### Parameters *szSignature* : [in] string containing the signature value encoded in base64. *lpData* : [in] byte array containing the input data to be verified. *nDataLen* : [in] specifying the length of the input data in bytes. *szCertOrKeyFile* : [in] specifying the X.509 certificate or public key file (or a string containing the certificate or key in [PEM format](#pemstring) or [base64 representation](#base64forcert)). *szAlgName* : [in] specifying the signature algorithm (case insensitive): `"sha1WithRSAEncryption"` (default) `"sha224WithRSAEncryption"` `"sha256WithRSAEncryption"` `"sha384WithRSAEncryption"` `"sha512WithRSAEncryption"` `"md5WithRSAEncryption"` `"ecdsaWithSHA1"` `"ecdsaWithSHA224"` `"ecdsaWithSHA256"` `"ecdsaWithSHA384"` `"ecdsaWithSHA512"` `"RSA-PSS-SHA1"` `"RSA-PSS-SHA224"` `"RSA-PSS-SHA256"` `"RSA-PSS-SHA384"` `"RSA-PSS-SHA512"` `"Ed25519"` *[New in v20.0]* (see Remarks) `"Ed448"` *[New in v22.0]* (see Remarks) or `""` to use the signature algorithm flag in *nOptions*, see [Specifying the signature algorithm in a SIG_ function](#sigalgorithm). *nOptions* : [in] Zero (0) for defaults. `PKI_SIG_USEDIGEST` to pass the digest value of the data-to-be-verified as a byte array in the *lpData* parameter instead of the data itself. `PKI_MGF_MGF1SHA1` (RSA-PSS only) to force the MGF hash function to be SHA-1 (default = same as signature hash algorithm). ### Returns (VBA/C) Zero (0) if the signature is valid; otherwise it returns a negative [error code](#errorcodes). ### VBA Wrapper Syntax Public Function [`sigVerifyData`](#VB_sigVerifyData) (szSignature As String, lpData() As Byte, szCertOrKey As String, szAlgName As String, Optional nOptions As Long = 0) As Long ### .NET Equivalent [Sig.VerifyData Method](#M_Sig_VerifyData) [Sig.VerifyDigest Method](#M_Sig_VerifyDigest) ### C++ (STL) Equivalent static bool [dipki::Sig::VerifyData](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_sig.html#afc0d9cb74fe7cfb2ce610f5f9c8c74fc "External link") (const std::string &sigStr, const bvec_t &data, const std::string &certOrKey, Alg alg=Alg::Default, VerifyOpts opts=VerifyOpts::Default) static [Sig.digest_is_verified](https://cryptosys.net/pki/pydocpki/class-stubs/Sig.html#cryptosyspki.Sig.digest_is_verified "External link")(sig, digest, certorkey, alg, verifyopts=VerifyOpts.DEFAULT) ### Python Equivalent `static [Sig.data_is_verified](https://cryptosys.net/pki/pydocpki/class-stubs/Sig.html#cryptosyspki.Sig.data_is_verified "External link")(sig, data, certorkey, alg, verifyopts=VerifyOpts.DEFAULT)` static [Sig.digest_is_verified](https://cryptosys.net/pki/pydocpki/class-stubs/Sig.html#cryptosyspki.Sig.digest_is_verified "External link")(sig, digest, certorkey, alg, verifyopts=VerifyOpts.DEFAULT) ### Remarks A signature value is considered valid if it can be decrypted by the public key in *szCertOrKeyFile* and the digest of the data matches the original digest of the data in the signature. The signature algorithm and hash algorithm used to create the signature value must be provided. For RSA-PSS, the MGF hash algorithm is assumed to be the same as the signature hash algorithm (see [RSA signature and encryption schemes](#rsaschemes)). If the signature was created using `mgf1SHA1` with a signature hash algorithm other than SHA-1, then you must add the option `PKI_MGF_MGF1SHA1`. Other combinations of signature hash algorithm/MGF hash algorithm are not supported. The `PKI_SIG_USEDIGEST` option cannot be used with Ed25519 or Ed448. The data to be verified must be passed *in toto* to the verify function. ### Example ``` Dim strSignature As String Dim strData As String Dim abData() As Byte Dim nDataLen As Long Dim strCertFile As String Dim strAlgName As String Dim nRet As Long ' Signature to be verified strSignature = _ "YK1aePtKQDDsVCyJdM0V9VOE6DZVTO3ZoyLV9BNcYmep0glwxU5mUQcLAUTUOETImTIN2Pp4Gffr" & _ "xqdxUoczLshnXBNhg7P4ofge+WlBgmcTCnVv27LHHZpmdEbjTg6tnPMb+2b4FvMZ0LfkMKXyiRVTmG4A" & _ "NyAmHH6QIsDZ8R8=" ' Data to be verified against signature = three-character ASCII string "abc" strData = "abc" strCertFile = "AliceRSASignByCarl.cer" strAlgName = "sha1WithRSAEncryption" ' Convert ASCII string to byte array abData = StrConv(strData, vbFromUnicode) nDataLen = Len(strData) ' Verify the signature... nRet = SIG_VerifyData(strSignature, abData(0), nDataLen, strCertFile, strAlgName, 0) Debug.Print "SIG_VerifyData returns " & nRet & " (expecting 0)" ``` ### See Also [SIG_VerifyFile](#SIG_VerifyFile) [[Contents](#topofpage)] [[Index](#index)] SIG_VerifyFile ----------------------------------------- Verify a signature value over data in a file. ### VBA/VB6 Syntax `Public Declare Function SIG_VerifyFile Lib "diCrPKI.dll" (ByVal strSignature As String, ByVal strDataFile As String, ByVal strCertOrKeyFile As String, ByVal strAlgName As String, ByVal nOptions As Long) As Long` `nRet = SIG_VerifyFile(strSignature, strDataFile, strCertOrKeyFile, strAlgName, nOptions)` ### C/C++ Syntax `long __stdcall SIG_VerifyFile(const char *szSignature, const char *szDataFile, const char *szCertOrKeyFile, const char *szAlgName, long nOptions);` ### Parameters *szSignature* : [in] string containing the signature value encoded in base64. *szDataFile* : [in] specifying the file containing the input data to be verified. *szCertOrKeyFile* : [in] specifying the X.509 certificate or public key file (or a string containing the certificate or key in [PEM format](#pemstring) or [base64 representation](#base64forcert)). *szAlgName* : [in] specifying the signature algorithm (case insensitive): `"sha1WithRSAEncryption"` (default) `"sha224WithRSAEncryption"` `"sha256WithRSAEncryption"` `"sha384WithRSAEncryption"` `"sha512WithRSAEncryption"` `"md5WithRSAEncryption"` [for legacy applications - not recommended for new implementations] `"ecdsaWithSHA1"` `"ecdsaWithSHA224"` `"ecdsaWithSHA256"` `"ecdsaWithSHA384"` `"ecdsaWithSHA512"` `"RSA-PSS-SHA1"` `"RSA-PSS-SHA224"` `"RSA-PSS-SHA256"` `"RSA-PSS-SHA384"` `"RSA-PSS-SHA512"` (Note that `Ed25519` and `Ed448` are not available with this function - see Remarks) or `""` to use the signature algorithm flag in *nOptions*, see [Specifying the signature algorithm in a SIG_ function](#sigalgorithm). *nOptions* : [in] Zero (0) for defaults. `PKI_MGF_MGF1SHA1` (RSA-PSS only) to force the MGF hash function to be SHA-1 (default = same as signature hash algorithm). ### Returns (VBA/C) Zero (0) if the signature is valid; otherwise it returns a negative [error code](#errorcodes). ### .NET Equivalent [Sig.VerifyFile Method](#M_Sig_VerifyFile) ### C++ (STL) Equivalent static bool [dipki::Sig::VerifyFile](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_sig.html#a4434b77b3411712a19c8cbfc0109c3ea "External link") (const std::string &sigStr, const std::string &dataFile, const std::string &certOrKey, Alg alg=Alg::Default, VerifyOpts opts=VerifyOpts::Default) ### Python Equivalent static [Sig.file_is_verified](https://cryptosys.net/pki/pydocpki/class-stubs/Sig.html#cryptosyspki.Sig.file_is_verified "External link")(sig, datafile, certorkey, alg, verifyopts=VerifyOpts.DEFAULT) ### Remarks This function is identical to `[SIG_VerifyData](#SIG_VerifyData)` except the data to be verified is in a file. The Ed25519 and Ed448 signature algorithms are not available with this function. To verify using Ed25519 or Ed448, read in the file to a byte array and use [SIG_VerifyData](#SIG_VerifyData). ### Example ``` Dim strSignature As String Dim strDataFile As String Dim strCertFile As String Dim strAlgName As String Dim nRet As Long ' Signature to be verified strSignature = _ "tLy6hJadL4w9JI/A/qLCG0Vz1fWPIrPMWD8NGmA5wP7HHlUID54elztUYrpdm9RFeh0RCMJ618dw" & _ "BpgIutuZg2qQ2i9uMUYB0DvZvkyeD6MqmtVa4ihgc9SLqhigKeP+KB7voEi7PH3hpEr9Wa3kn4mb" & _ "PpeD1VHSzgu/qirjOaA=" ' File to be verified against signature = three-character ASCII string "abc" strDataFile = "abc.txt" strCertFile = "AliceRSASignByCarl.cer" strAlgName = "sha256WithRSAEncryption" ' Verify the signature over the data in the file... nRet = SIG_VerifyFile(strSignature, strDataFile, strCertFile, strAlgName, 0) Debug.Print "SIG_VerifyFile returns " & nRet & " (expecting 0)" ``` ``` SIG_VerifyFile returns 0 (expecting 0) ``` ### See Also [SIG_VerifyData](#SIG_VerifyData) [[Contents](#topofpage)] [[Index](#index)] SMIME_Extract --------------------------------------- Extract the body from an S/MIME entity. ### VBA/VB6 Syntax `Public Declare Function SMIME_Extract Lib "diCrPKI.dll" (ByVal strFileOut As String, ByVal strFileIn As String, ByVal nOptions As Long) As Long` `nRet = SMIME_Extract(strFileOut, strFileOut, nOptions)` ### C/C++ Syntax `long __stdcall SMIME_Extract(const char *szFileOut, const char *szFileIn, long nOptions);` ### Parameters *szFileOut* : [in] string specifying the filename of the output file to be created. *szFileIn* : [in] string specifying the filename of the input file. *nOptions* : [in] Zero (0) for defaults. `PKI_SMIME_ENCODE_BASE64` to encode the output in base64 encoding (default is binary). ### Returns (VBA/C) A positive number giving the size of the output file in bytes; or a negative [error code](#errorcodes). ### .NET Equivalent [Smime.Extract Method](#M_Smime_Extract) ### C++ (STL) Equivalent static int [dipki::Smime::Extract](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_smime.html#a440c2d87ffd605a72a6ff1ee2e6b419f "External link") (const std::string &outputFile, const std::string &inputFile, Encoding encoding=Encoding::Default) ### Python Equivalent static [Smime.extract](https://cryptosys.net/pki/pydocpki/class-stubs/Smime.html#cryptosyspki.Smime.extract "External link")(outputfile, inputfile, opts=0) ### Remarks This is designed to extract the body from an S/MIME entity with a content type of `application/pkcs7-mime` with base64 or binary transfer encoding. In practice, it will extract the body from almost any type of S/MIME (or MIME) file, except one with quoted-printable transfer encoding. ### Example ``` nRet = SMIME_Extract("cmsalice2bob-extracted.p7m", "cmsalice2bob-smime-env.txt", 0) ``` In this example, the input S/MIME file `cmsalice2bob-smime-env.txt` was created from a CMS enveloped-data file using [`SMIME_Wrap`](#SMIME_Wrap). The output should be a binary file identical to the original binary CMS file. ### See Also [SMIME_Wrap](#SMIME_Wrap) [[Contents](#topofpage)] [[Index](#index)] SMIME_Query ----------------------------------- Query an S/MIME entity. ### VBA/VB6 Syntax `Public Declare Function SMIME_Query Lib "diCrPKI.dll" (ByVal strOutput As String, ByVal nOutChars As Long, ByVal strFileIn As String, ByVal strQuery As String, ByVal nOptions As Long) As Long` `nRet = SMIME_Query(strFileOut, strFileOut, strQuery, nOptions)` ### C/C++ Syntax `long __stdcall SMIME_Query(char *szOutput, long nOutChars, const char *szFileIn, const char *szQuery, long nOptions);` ### Parameters *szOutput* : [out] string of sufficient length to receive the output. *nOutChars* : [in] specifying the maximum number of characters to be received. *szFileIn* : [in] string specifying the filename of the input file. *szQuery* : [in] specifying the query (see Remarks below). *nOptions* : [in] option flags: not used in this release. Specify zero. ### Returns (VBA/C) If successful, the return value is a positive number indicating the number of characters (bytes) in the output string, or number of characters required if *nOutChars* was set to zero. If the item queried cannot be found, the return value is zero. If there is an error (e.g. invalid input), it returns a negative [error code](#errorcodes). ### VBA Wrapper Syntax Public Function [`smimeQuery`](#VB_smimeQuery) (szFileIn As String, szQuery As String, Optional nOptions As Long = 0) As String ### .NET Equivalent [Smime.Query Method](#M_Smime_Query) ### C++ (STL) Equivalent static std::string [dipki::Smime::Query](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_smime.html#a1f6f809a61f7ac1b8680ffdf242a6757 "External link") (const std::string &inputFile, const std::string &query) ### Python Equivalent static [Smime.query](https://cryptosys.net/pki/pydocpki/class-stubs/Smime.html#cryptosyspki.Smime.query "External link")(filename, query) ### Remarks Valid queries are (case-insensitive): | Query String | Returns | | --- | --- | | `content-type` | Value of Content-Type, e.g. "application/pkcs7-mime" | | `smime-type` | Value of smime-type parameter of Content-Type, e.g. "enveloped-data" | | `encoding` | Value of Content-Transfer-Encoding, e.g. "base64" | | `name` | Value of name parameter of Content-Type, e.g. "smime.p7m" | | `filename` | Value of filename parameter of Content-Disposition, e.g. "smime.p7m" | If no value is found corresponding to the query then the zero-length empty string `""` is output. For the "raw" VBA/C function, the user must allocate an output string buffer *szOutput* of the required length. Specify a zero *nOutChars* or an empty string for *szOutput* to find the required length. ANSI C users [must add one to this value](#cusersaddone) when allocating memory. ### Example (VBA core function) ``` Dim strQuery As String Dim strOutput As String Dim nRet As Long Dim strFileIn As String strFileIn = "cmsalice2bob-smime-env.txt" Debug.Print "FILE: " & strFileIn ' Make a buffer large enough to receive output strOutput = String(512, " ") strQuery = "content-type" nRet = SMIME_Query(strOutput, Len(strOutput), strFileIn, strQuery, 0) If nRet <= 0 Then Exit Sub ' catch error Debug.Print strQuery & "=" & Left(strOutput, nRet) strQuery = "smime-type" nRet = SMIME_Query(strOutput, Len(strOutput), strFileIn, strQuery, 0) If nRet <= 0 Then Exit Sub ' catch error Debug.Print strQuery & "=" & Left(strOutput, nRet) strQuery = "encoding" nRet = SMIME_Query(strOutput, Len(strOutput), strFileIn, strQuery, 0) If nRet <= 0 Then Exit Sub ' catch error Debug.Print strQuery & "=" & Left(strOutput, nRet) strQuery = "filename" nRet = SMIME_Query(strOutput, Len(strOutput), strFileIn, strQuery, 0) If nRet <= 0 Then Exit Sub ' catch error Debug.Print strQuery & "=" & Left(strOutput, nRet) ``` ``` FILE: cmsalice2bob-smime-env.txt content-type=application/pkcs7-mime smime-type=enveloped-data encoding=base64 filename=smime.p7m ``` ### Example (VBA wrapper function) ``` Dim strFileIn As String Dim strQuery As String strFileIn = "cmsalice2bob-smime-env.txt" Debug.Print "FILE: " & strFileIn strQuery = "content-type" Debug.Print strQuery & "=" & smimeQuery(strFileIn, strQuery, 0) strQuery = "smime-type" Debug.Print strQuery & "=" & smimeQuery(strFileIn, strQuery, 0) strQuery = "encoding" Debug.Print strQuery & "=" & smimeQuery(strFileIn, strQuery, 0) strQuery = "filename" Debug.Print strQuery & "=" & smimeQuery(strFileIn, strQuery, 0) ``` ### See Also [SMIME_Extract](#SMIME_Extract) [[Contents](#topofpage)] [[Index](#index)] SMIME_Wrap --------------------------------- Wrap a CMS object in an S/MIME entity. ### VBA/VB6 Syntax `Public Declare Function SMIME_Wrap Lib "diCrPKI.dll" (ByVal strFileOut As String, ByVal strFileIn As String, ByVal strFeatures As String, ByVal nOptions As Long) As Long` `nRet = SMIME_Wrap(strFileOut, strFileIn, strFeatures, nOptions)` ### C/C++ Syntax `long __stdcall SMIME_Wrap(const char *szFileOut, const char *szFileIn, const char *szFeatures, long nOptions);` ### Parameters *szFileOut* : [in] string specifying the filename of the output file to be created. *szFileIn* : [in] string specifying the filename of the input file. *szFeatures* : [in] string to specify special features. For future use. Leave empty `""` or `NULL` for defaults. *nOptions* : [in] Zero (0) for defaults. `PKI_SMIME_ENCODE_BINARY` to encode the body in binary encoding (default is base64). `PKI_SMIME_ADDX` to add an "x-" to the content subtype. ### Returns (VBA/C) A positive number giving the size of the output file in bytes; or a negative [error code](#errorcodes). ### .NET Equivalent [Smime.Wrap Method](#M_Smime_Wrap) ### C++ (STL) Equivalent static int [dipki::Smime::Wrap](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_smime.html#a10d307291729cb54cdfdc5f4c11f3469 "External link") (const std::string &outputFile, const std::string &inputFile, Encoding encoding=Encoding::Default, AdvOpts advopts=AdvOpts::Default) ### Python Equivalent static [Smime.wrap](https://cryptosys.net/pki/pydocpki/class-stubs/Smime.html#cryptosyspki.Smime.wrap "External link")(outputfile, inputfile, opts=0) ### Remarks This forms an S/MIME entity with a Content-Type of `application/pkcs7-mime` from a binary CMS object. It works in file-to-file mode only. The input file is expected to be a binary CMS object of type enveloped-data, signed-data or compressed-data; otherwise it is an error. The type of input file is detected automatically. The output is a text file with the correct S/MIME headers according to [[SMIME-MSG](#SMIME-MSG)]. By default the body is encoded in base64. Use the `PKI_SMIME_ENCODE_BINARY` option to encode the body in "binary" instead. Use the `PKI_SMIME_ADDX` option to change the Content-Type to `application/x-pkcs7-mime` for compatibility with legacy applications. S/MIME signed messages with the `multipart/signed` format are currently not supported. ### Example ``` nRet = SMIME_Wrap("cmsalice2bob-smime-env.txt", "cmsalice2bob.p7m", "", 0) ``` In this example, the binary file `cmsalice2bob.p7m` was created using [`CMS_MakeEnvData`](#CMS_MakeEnvData). The output file should look like the following. ``` Content-Type: application/pkcs7-mime; smime-type=enveloped-data; id="smime.p7m" Content-Transfer-Encoding: base64 Content-Disposition: attachment; fileid="smime.p7m" MIAGCSqGSIb3DQEHA6CAMIACAQAxgcAwgb0CAQAwJjASMRAwDgYDVQQDEwdDYXJs UlNBAhBGNGvHgABWvBHTbi7NXXHQMA0GCSqGSIb3DQEBAQUABIGAFx80IYQbAX8+ 7PIXJzUInDUydJv9tgogwzQY8KHwneD1Wcihc/Thi3QtSIQu4bnoPlSbGdF76SuE Cajdnq5PDU34SnMywq8fyBxDM0ayUfYfMozZOhnM4mr9F4lF3zqtAhnukQF8b+Hv cTgt4XHHrk2P5vHhdtaA4spSM9kDtpwwgAYJKoZIhvcNAQcBMBQGCCqGSIb3DQMH BAh7TZ7TVakVU6CABCCNGoP9xsyKSFr1lFrffFky8Ym+efPbS4jx1ODxWzHa3wAA AAAAAAAAAAA= ``` ### See Also [SMIME_Extract](#SMIME_Extract) [[Contents](#topofpage)] [[Index](#index)] TDEA_B64Mode ------------------------------------- Encrypts or decrypts data encoded in base64 using a specified mode. The key and initialization vector are required in base64. ### VBA/VB6 Syntax `Public Declare Function TDEA_B64Mode Lib "diCrPKI.dll" (ByVal strOutput As String, ByVal strInput As String, ByVal strKey As String, ByVal fEncrypt As Long, ByVal strMode As String, ByVal strIV As String) As Long` `nRet = TDEA_B64Mode(strOutput, strInput, strKey, fEncrypt, strMode, strIV)` ### C/C++ Syntax `long __stdcall TDEA_B64Mode(char *szOutput, const char *szInput, const char *szKey, long fEncrypt, const char *szMode, const char *szIV);` ### Parameters *szOutput* : [out] of sufficient length to receive the output. *szInput* : [in] containing the input data in base64. *szKey* : [in] containing the key in base64 format. *fEncrypt* : [in] direction flag: set as `ENCRYPT` (True) to encrypt or `DECRYPT` (False) to decrypt. *szMode* : [in] specifying the confidentiality mode: `"ECB"` for Electronic Codebook mode, `"CBC"` for Cipher Block Chaining mode, `"CFB"` for 64-bit Cipher Feedback mode, `"OFB"` for Output Feedback mode, or `"CTR"` for Counter mode. *szIV* : [in] containing the initialization vector (IV), if required, in base64 format. ### Returns (VBA/C) If successful, the return value is zero; otherwise it returns a nonzero [error code](#errorcodes). ### .NET Equivalent [Tdea.Encrypt Method](#M_Tdea_Encrypt_StringStringModeStringEncodingBase) (String, String, Mode, String, EncodingBase) [Tdea.Decrypt Method](#M_Tdea_Decrypt_StringStringModeStringEncodingBase) (String, String, Mode, String, EncodingBase) ### Remarks For ECB and CBC modes, the input string *szInput* must represent an exact multiple of eight bytes when decoded otherwise a "Data not a valid length" error will result. The key string *szKey* must represent exactly 24 bytes when decoded. The initialization vector string *szIV* must represent exactly 8 bytes when decoded unless *szMode* is `ECB`, in which case *szIV* is ignored (use `""`). Valid base64 characters are [A-Za-z0-9+/] with '=' used as a padding character. The output string *szOutput* must be set up with at least the same number of characters as the input string before calling. The variables *szOutput* and *szInput* should be different. ### Example Examples in base64 are pretty obscure to read. This is the same example from [`TDEA_HexMode`](#TDEA_HexMode) using base64 strings instead. ``` Dim nRet As Long Dim sHexCorrect As String Dim sHexInput As String Dim sHexKey As String Dim sHexInitV As String Dim sOutput As String Dim sInput As String Dim sKey As String Dim sInitV As String Dim bEncrypt As Boolean Dim sCorrect As String ' Start with input in hex sHexInput = "5468697320736F6D652073616D706520636F6E74656E742E0808080808080808" ' T h i s _ s o m e _ s a m p e _ c o n t e n t . (padding 8 x 08) sHexKey = "737C791F25EAD0E04629254352F7DC6291E5CB26917ADA32" sHexInitV = "B36B6BFB6231084E" sHexCorrect = "d76fd1178fbd02f84231f5c1d2a2f74a4159482964f675248254223daf9af8e4" ' Convert to base64 sInput = cnvB64StrFromBytes(cnvBytesFromHexStr(sHexInput)) sKey = cnvB64StrFromBytes(cnvBytesFromHexStr(sHexKey)) sInitV = cnvB64StrFromBytes(cnvBytesFromHexStr(sHexInitV)) sCorrect = cnvB64StrFromBytes(cnvBytesFromHexStr(sHexCorrect)) ' Set sOutput to be same length as sInput sOutput = String(Len(sInput), " ") Debug.Print "KY=" & sKey Debug.Print "PT=" & sInput Debug.Print "IV=" & sInitV nRet = TDEA_B64Mode(sOutput, sInput, sKey, ENCRYPT, "CBC", sInitV) Debug.Print "CT=" & sOutput & nRet Debug.Print "OK=" & sCorrect sInput = sOutput nRet = TDEA_B64Mode(sOutput, sInput, sKey, DECRYPT, "CBC", sInitV) Debug.Print "P'=" & sOutput & nRet ``` ### See Also [TDEA_BytesMode](#TDEA_BytesMode) [TDEA_HexMode](#TDEA_HexMode) [[Contents](#topofpage)] [[Index](#index)] TDEA_BytesMode ----------------------------------------- Encrypts or decrypts an array of Bytes in one step using a specified mode. ### VBA/VB6 Syntax `Public Declare Function TDEA_BytesMode Lib "diCrPKI.dll" (ByRef lpOutput As Byte, ByRef lpInput As Byte, ByVal nDataLen As Long, ByRef lpKey As Byte, ByVal fEncrypt As Long, ByVal strMode As String, ByRef lpIV As Byte) As Long` `nRet = TDEA_BytesMode(lpOutput(0), lpInput(0), nDataLen, lpKey(0), fEncrypt, strMode, lpIV(0)) ' Note the "(0)" after the byte array parameters` ### C/C++ Syntax `long __stdcall TDEA_BytesMode(unsigned char *lpOutput, const unsigned char *lpData, long nDataLen, const unsigned char *lpKey, long fEncrypt, const char *szMode, const unsigned char *lpIV);` ### Parameters *lpOutput* : [out] array of sufficient length to receive the output. *lpData* : [in] array containing the input data. *nDataLen* : [in] equal to length of the input data in bytes. *lpKey* : [in] array containing the key. *fEncrypt* : [in] direction flag: set as `ENCRYPT` (True) to encrypt or `DECRYPT` (False) to decrypt. *szMode* : [in] specifying the confidentiality mode: `"ECB"` for Electronic Codebook mode, `"CBC"` for Cipher Block Chaining mode, `"CFB"` for 64-bit Cipher Feedback mode, `"OFB"` for Output Feedback mode, or `"CTR"` for Counter mode. *lpIV* : [in] array containing the initialization vector (IV), or zero (0) for ECB mode. ### Returns (VBA/C) If successful, the return value is zero; otherwise it returns a nonzero [error code](#errorcodes). ### .NET Equivalent [Tdea.Encrypt Method](#M_Tdea_Encrypt_ByteByteModeByte) (Byte[], Byte[], Mode, Byte[]) [Tdea.Decrypt Method](#M_Tdea_Decrypt_ByteByteModeByte) (Byte[], Byte[], Mode, Byte[]) ### Remarks For ECB and CBC modes, the input data *lpInput* *must* be a multiple of 8 bytes long otherwise a "Data not a valid length" error will result. The key *lpKey* must be exactly 24 bytes long and the IV, if required, exactly 8 bytes long. The output array *lpOutput* must be at least *nDataLen* bytes long. *lpOutput* and *lpInput* may be the same. ### Example ``` Dim nRet As Long Dim sOutput As String Dim sInput As String Dim sKey As String Dim sHexIV As String Dim sCorrect As String Dim nKeyLen As Long Dim nDataLen As Long Dim nIVLen As Long Dim aKey() As Byte Dim aResult() As Byte Dim aData() As Byte Dim aInitV() As Byte sKey = "0123456789abcdeffedcba987654321089abcdef01234567" sHexIV = "1234567890abcdef" sInput = "Now is the time for all " sCorrect = "204011f986e35647199e47af391620c5bb9a5bcfc86db0bb" ' Convert hex strings to byte arrays nKeyLen = Len(sKey) \ 2 ReDim aKey(nKeyLen) Call CNV_BytesFromHexStr(aKey(0), nKeyLen, sKey) nIVLen = Len(sHexIV) \ 2 ReDim aInitV(nIVLen) Call CNV_BytesFromHexStr(aInitV(0), nIVLen, sHexIV) ' Convert string to byte array and dimension aResult array aData() = StrConv(sInput, vbFromUnicode) nDataLen = UBound(aData) + 1 ReDim aResult(nDataLen - 1) Debug.Print "KY=" & cnvHexStrFromBytes(aKey) Debug.Print "IV=" & cnvHexStrFromBytes(aInitV) Debug.Print "PT=" & "[" & sInput & "]" ' Encrypt in one-off process nRet = TDEA_BytesMode(aResult(0), aData(0), nDataLen, _ aKey(0), ENCRYPT, "CBC", aInitV(0)) Debug.Print "CT=" & cnvHexStrFromBytes(aResult) & nRet Debug.Print "OK=" & sCorrect ' Now decrypt back nRet = TDEA_BytesMode(aData(0), aResult(0), nDataLen, _ aKey(0), DECRYPT, "cbc", aInitV(0)) sOutput = StrConv(aData(), vbUnicode) Debug.Print "P'=" & "[" & sOutput & "]" & nRet ``` This should result in output as follows: ``` KY=0123456789ABCDEFFEDCBA987654321089ABCDEF01234567 IV=1234567890ABCDEF PT=[Now is the time for all ] CT=204011F986E35647199E47AF391620C5BB9A5BCFC86DB0BB 0 OK=204011f986e35647199e47af391620c5bb9a5bcfc86db0bb P'=[Now is the time for all ] 0 ``` ### See Also [TDEA_HexMode](#TDEA_HexMode) [TDEA_B64Mode](#TDEA_B64Mode) [TDEA_File](#TDEA_File) [[Contents](#topofpage)] [[Index](#index)] TDEA_File ------------------------------- Encrypts or decrypts a file using a specified mode. The key and initialization vector are passed as arrays of bytes. PKCS-5/7 padding is used. ### VBA/VB6 Syntax `Public Declare Function TDEA_File Lib "diCrPKI.dll" (ByVal strFileOut As String, ByVal strFileIn As String, ByRef lpKey As Byte, ByVal fEncrypt As Long, ByVal strMode As String, ByRef lpInitV As Byte) As Long` `nRet = TDEA_File(strFileOut, strFileIn, lpKey(0), fEncrypt, strMode, lpInitV(0))` ### C/C++ Syntax `long __stdcall TDEA_File(const char *szFileOut, const char *szFileIn, const unsigned char *lpKey, long fEncrypt, const char *szMode, const unsigned char *lpIV);` ### Parameters *szFileOut* : [in] with the full path name of the output file to be created. *szFileIn* : [in] with the full path name of the input file to be processed. *lpKey* : [in] array containing the key. *fEncrypt* : [in] direction flag: set as `ENCRYPT` (True) to encrypt or `DECRYPT` (False) to decrypt. *szMode* : [in] specifying the confidentiality mode: `"ECB"` for Electronic Codebook mode, `"CBC"` for Cipher Block Chaining mode, `"CFB"` for 64-bit Cipher Feedback mode, `"OFB"` for Output Feedback mode, or `"CTR"` for Counter mode. *lpIV* : [in] array containing the initialization vector (IV), or zero (0) for ECB mode. ### Returns (VBA/C) If successful, the return value is zero; otherwise it returns a nonzero [error code](#errorcodes). ### .NET Equivalent [Tdea.FileEncrypt Method](#M_Tdea_FileEncrypt_StringStringByteModeByte) (String, String, Byte[], Mode, Byte[]) [Tdea.FileDecrypt Method](#M_Tdea_FileDecrypt_StringStringByteModeByte) (String, String, Byte[], Mode, Byte[]) ### Remarks The key array *abKey()* must be exactly 16 bytes long. The initialization vector *abInitV()* must be exactly the block size of 16 bytes long, except for ECB mode, where it is ignored (use `0`). The output file *szFileOut* will be overwritten without warning. If there is an error, the output file will **not exist**. The input and output files must **not** be the same. In ECB and CBC modes, a padding string will be added or assumed according to the method outlined in Section 6.3 of [[CMS](#CMS)], which is the same as the padding method in [[PKCS7](#PKCS7)] section 10.3 and [[PKCS5](#PKCS5)] section 6.1.1 and [[RFC1423](#RFC1423)] para 1.1. ### Example ``` Const MY_PATH As String = "" Dim aKey() As Byte Dim strFileOut As String Dim strFileIn As String Dim strFileChk As String Dim nRet As Long ' Construct full path names to files strFileIn = MY_PATH & "hello.txt" strFileOut = MY_PATH & "hello.tdea.enc.dat" strFileChk = MY_PATH & "hello.tdea.chk.txt" ' Create the key as an array of bytes ' This creates an array of 24 bytes {&HFE, &HDC, ... &H10} aKey = cnvBytesFromHexStr("fedcba9876543210fedcba9876543210fedcba9876543210") ' Encrypt plaintext file to ciphertext ' Output file = 16-byte ciphertext file hello.enc nRet = TDEA_File(strFileOut, strFileIn, aKey(0), ENCRYPT, "ECB", 0) Debug.Print nRet ' Now decrypt it nRet = TDEA_File(strFileChk, strFileOut, aKey(0), DECRYPT, "ECB", 0) Debug.Print nRet ``` ### See Also [TDEA_BytesMode](#TDEA_BytesMode) [[Contents](#topofpage)] [[Index](#index)] TDEA_HexMode ------------------------------------- Encrypts or decrypts data represented as a hexadecimal string using a specified mode. The key and initialization vector are represented as a hexadecimal string. ### VBA/VB6 Syntax `Public Declare Function TDEA_HexMode Lib "diCrPKI.dll" (ByVal strOutput As String, ByVal strInput As String, ByVal strKey As String, ByVal fEncrypt As Long, ByVal strMode As String, ByVal strIV As String) As Long` `nRet = TDEA_HexMode(strOutput, strInput, strKey, fEncrypt, strMode, strIV)` ### C/C++ Syntax `long __stdcall TDEA_HexMode(char *szOutput, const char *szInput, const char *szKey, long fEncrypt, const char *szMode, const char *szIV);` ### Parameters *szOutput* : [out] of sufficient length to receive the output. *szInput* : [in] containing the input data in hex format. *szKey* : [in] containing the key in hex format. *fEncrypt* : [in] direction flag: set as `ENCRYPT` (True) to encrypt or `DECRYPT` (False) to decrypt. *szMode* : [in] specifying the confidentiality mode: `"ECB"` for Electronic Codebook mode, `"CBC"` for Cipher Block Chaining mode, `"CFB"` for 64-bit Cipher Feedback mode, `"OFB"` for Output Feedback mode, or `"CTR"` for Counter mode. *szIV* : [in] containing the initialization vector (IV), if required, in hex format. ### Returns (VBA/C) If successful, the return value is zero; otherwise it returns a nonzero [error code](#errorcodes). ### .NET Equivalent [Tdea.Encrypt Method](#M_Tdea_Encrypt_StringStringModeString) (String, String, Mode, String) [Tdea.Decrypt Method](#M_Tdea_Decrypt_StringStringModeString) (String, String, Mode, String) ### Remarks For ECB and CBC modes, the length of the input string *szInput* must be a multiple of 16 hex characters long (i.e. representing a multiple of 8 bytes) otherwise an error will result. The key string *szKey* must be exactly 48 hex characters long (i.e. representing exactly 24 bytes/192 bits). The initialization vector string *szIV* must be exactly 16 hex characters long (i.e. representing exactly the block size of 8 bytes) unless *szMode* is `ECB`, in which case *szIV* is ignored (use `""`). Valid hexadecimal characters are [0-9A-Fa-f]. The output string *szOutput* must be set up with the same number of characters as the input string before calling. The variables *szOutput* and *szInput* should be different. ### Example This example is from Section 8.1 of [[SMIME-EX]](#SMIME-EX). ``` Dim nRet As Long Dim sOutput As String Dim sInput As String Dim sKey As String Dim sInitV As String Dim sCorrect As String sInput = "5468697320736F6D652073616D706520636F6E74656E742E0808080808080808" ' T h i s _ s o m e _ s a m p e _ c o n t e n t . (padding 8 x 08) sKey = "737C791F25EAD0E04629254352F7DC6291E5CB26917ADA32" sInitV = "B36B6BFB6231084E" sCorrect = "d76fd1178fbd02f84231f5c1d2a2f74a4159482964f675248254223daf9af8e4" ' Set sOutput to be same length as sInput sOutput = String(Len(sInput), " ") Debug.Print "KY=" & sKey Debug.Print "PT=" & sInput nRet = TDEA_HexMode(sOutput, sInput, sKey, ENCRYPT, "CBC", sInitV) Debug.Print "CT=" & sOutput & nRet Debug.Print "OK=" & sCorrect sInput = sOutput nRet = TDEA_HexMode(sOutput, sInput, sKey, DECRYPT, "CBC", sInitV) Debug.Print "P'=" & sOutput & nRet ``` This should result in output as follows: ``` KY=737C791F25EAD0E04629254352F7DC6291E5CB26917ADA32 PT=5468697320736F6D652073616D706520636F6E74656E742E0808080808080808 CT=D76FD1178FBD02F84231F5C1D2A2F74A4159482964F675248254223DAF9AF8E4 0 OK=d76fd1178fbd02f84231f5c1d2a2f74a4159482964f675248254223daf9af8e4 P'=5468697320736F6D652073616D706520636F6E74656E742E0808080808080808 0 ``` ### See Also [TDEA_BytesMode](#TDEA_BytesMode) [TDEA_B64Mode](#TDEA_B64Mode) [[Contents](#topofpage)] [[Index](#index)] WIPE_Data ------------------------------- Zeroise data in memory. ### VBA/VB6 Syntax `Public Declare Function WIPE_Data Lib "diCrPKI.dll" (ByRef lpData As Byte, ByVal nBytes As Long) As Long` Alternative aliases for VBA/VB6 users to deal with Byte and String types explicitly: `Public Declare Function WIPE_Bytes Lib "diCrPKI.dll" Alias "WIPE_Data" (ByRef lpData As Byte, ByVal nBytes As Long) As Long Public Declare Function WIPE_String Lib "diCrPKI.dll" Alias "WIPE_Data" (ByVal strData As String, ByVal nStrLen As Long) As Long` `nRet = WIPE_Data(lpData(0), nBytes) ' Note the "(0)" after the byte array parameters` VBA/VB6 aliases only: `nRet = WIPE_Bytes(lpData(0), nBytes) nRet = WIPE_String(strData, nStrLen)` ### C/C++ Syntax `long __stdcall WIPE_Data(void *lpData, long nDataLen);` ### Parameters *lpData* : [in,out] array to be cleared. *nDataLen* : [in] number of bytes in array to be cleared. ### Returns (VBA/C) If successful, the return value is zero; otherwise it returns a nonzero [error code](#errorcodes). ### VBA Wrapper Syntax Public Function [`wipeBytes`](#VB_wipeBytes) (ByRef lpToWipe() As Byte) As Byte() Public Function [`wipeString`](#VB_wipeString) (ByRef szToWipe As String) As String ### .NET Equivalent [Wipe.Data Method](#M_Wipe_Data) [Wipe.String Method](#M_Wipe_String) ### C++ (STL) Equivalent static bool [dipki::Wipe::Data](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_wipe.html#a6d3d230ff058e62ad26ec96f5b44d5d5 "External link") (bvec_t &data) static bool [dipki::Wipe::String](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_wipe.html#a7f4bcf4a0356d51efe7788b360bab3d4 "External link") (std::string &s) ### Python Equivalent static [Wipe.data](https://cryptosys.net/pki/pydocpki/class-stubs/Wipe.html#cryptosyspki.Wipe.data "External link")(data) ### Remarks This function does not free any memory; it just zeroises it. ### Example (VBA core function) ``` Dim lpData() As Byte lpData = ... ' n bytes of data nRet = WIPE_Data(lpData(0), n) ``` ``` Dim strData As String strData = "my deepest secrets" nRet = WIPE_String(strData, Len(strData)) strData = "" ``` ``` long pwdlen; char password[256]; pwdlen = PWD_Prompt(password, sizeof(password)-1, "Test"); if (pwdlen >= 0) printf("Password entered=[%s]\n", password); else printf("No password entered\n"); /* ... do something with password ... */ WIPE_Data(password, pwdlen); ``` ### Examples (VBA wrapper function) ``` Dim strData As String strData = "my deepest secrets" strData = wipeString(strData) ``` ``` Dim lpData() As Byte lpData = cnvBytesFromHexStr("DEADBEEF") Debug.Print "BEFORE: " & cnvHexStrFromBytes(lpData) Call wipeBytes(lpData) Debug.Print "AFTER: '" & cnvHexStrFromBytes(lpData) & "'" ``` ### See Also [[Contents](#topofpage)] [[Index](#index)] WIPE_File ------------------------------- Wipe and delete a file using secure 7-pass DOD standards. ### VBA/VB6 Syntax `Public Declare Function WIPE_File Lib "diCrPKI.dll" (ByVal strFileName As String, ByVal nOptions As Long) As Long` `nRet = WIPE_File(strFileName, nOptions)` ### C/C++ Syntax `long __stdcall WIPE_File(const char *szFileName, long nOptions);` ### Parameters *szFileName* : [in] specifying the file to be deleted. *nOptions* : [in] Option flags *[New in v12.0]*. Select one of: `PKI_WIPEFILE_DOD7` (0) to use DOD 7-pass (default) `PKI_WIPEFILE_SIMPLE` to overwrite with single pass of zero bytes (quicker but less secure). ### Returns (VBA/C) If successful, the return value is zero; otherwise it returns a nonzero [error code](#errorcodes). ### .NET Equivalent [Wipe.File Method](#M_Wipe_File) ### C++ (STL) Equivalent static bool [dipki::Wipe::File](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_wipe.html#a487b2823f03489759882f38617e15020 "External link") (const std::string fileName, Opts opts=Opts::Dod7Pass) ### Python Equivalent static [Wipe.file](https://cryptosys.net/pki/pydocpki/class-stubs/Wipe.html#cryptosyspki.Wipe.file "External link")(filename, opts=Options.DEFAULT) ### Remarks Wipes a file using the 7-pass DOD Standard according to [[NISPOM](#NISPOM)] before deleting. ### Example ``` nRet = WIPE_File("ToDelete.txt", 0) ``` ### See Also [[Contents](#topofpage)] [[Index](#index)] X509_CertExpiresOn ------------------------------------------------- Returns the date and time an X.509 certificate expires. ### VBA/VB6 Syntax `Public Declare Function X509_CertExpiresOn Lib "diCrPKI.dll" (ByVal strCertFile As String, ByVal strOutput As String, ByVal nOutChars As Long, ByVal nOptions As Long) As Long` `nRet = X509_CertExpiresOn(strCertFile, strOutput, nOutChars, nOptions)` ### C/C++ Syntax `long __stdcall X509_CertExpiresOn(const char *szCertFile, char *szOutput, long nOutChars, long nOptions);` ### Parameters *szCertFile* : [in] with the filename of the X.509 certificate (or [base64 representation](#base64forcert)). *szOutput* : [out] to receive the time-date string. *nOutChars* : [in] specifying the maximum length of the time-date string. *nOptions* : [in] option flags: not used in this release. Specify zero. ### Returns (VBA/C) Returns the number of characters set in *szOutput*. If *nOutChars* is zero it returns the maximum number of characters required (currently 20, but don't assume that for future releases). C/C++ users should allocate one extra for the terminating NUL character. If an error occurs, it returns a negative [error code](#errorcodes). ### .NET Equivalent [X509.CertExpiresOn Method](#M_X509_CertExpiresOn) ### Remarks The time format is in accordance with [ISO 8601](#ISO8601) and will always be of the form YYYY-MM-DDThh:mm:ssZ. The time is always given as GMT (Greenwich Mean Time, UTC, Zulu Time). ### Example ``` Dim nRet As Long Dim strCertName As String Dim strDateTime As String * 32 strCertName = "AliceRSASignByCarl.cer" ' Change your dir to suit nRet = X509_CertIssuedOn(strCertName, strDateTime, Len(strDateTime), 0) Debug.Print "X509_CertIssuedOn returns " & nRet & " for " & strCertName & ": " & strDateTime nRet = X509_CertExpiresOn(strCertName, strDateTime, Len(strDateTime), 0) Debug.Print "X509_CertExpiresOn returns " & nRet & " for " & strCertName & ": " & strDateTime ``` Should result in (in all locales): ``` X509_CertIssuedOn returns 20 for AliceRSASignByCarl.cer: 1999-09-19T01:08:47Z X509_CertExpiresOn returns 20 for AliceRSASignByCarl.cer: 2039-12-31T23:59:59Z ``` ### See Also [X509_CertIssuedOn](#X509_CertIssuedOn) [X509_CertIsValidNow](#X509_CertIsValidNow) [X509_QueryCert](#X509_QueryCert) [[Contents](#topofpage)] [[Index](#index)] X509_CertIssuedOn ----------------------------------------------- Returns the date and time an X.509 certificate was issued. ### VBA/VB6 Syntax `Public Declare Function X509_CertIssuedOn Lib "diCrPKI.dll" (ByVal strCertFile As String, ByVal strOutput As String, ByVal nOutChars As Long, ByVal nOptions As Long) As Long` `nRet = X509_CertIssuedOn(strCertFile, strOutput, nOutChars, nOptions)` ### C/C++ Syntax `long __stdcall X509_CertIssuedOn(const char *szCertFile, char *szOutput, long nOutChars, long nOptions);` ### Parameters *szCertFile* : [in] with the filename of the X.509 certificate (or [base64 representation](#base64forcert)). *szOutput* : [out] to receive the time-date string. *nOutChars* : [in] specifying the maximum length of the time-date string. *nOptions* : [in] option flags: not used in this release. Specify zero. ### Returns (VBA/C) Returns the number of characters set in *szOutput*. If *nOutChars* is zero it returns the maximum number of characters required (currently 20, but don't assume that for future releases). C/C++ users should allocate one extra for the terminating NUL character. If an error occurs, it returns a negative [error code](#errorcodes). ### .NET Equivalent [X509.CertIssuedOn Method](#M_X509_CertIssuedOn) ### Remarks The time format is in accordance with [ISO 8601](#ISO8601) and will always be of the form YYYY-MM-DDThh:mm:ssZ. The time is always given as GMT (Greenwich Mean Time, UTC, Zulu Time). ### Example See [`X509_CertExpiresOn`](#X509_CertExpiresOn). ### See Also [X509_CertExpiresOn](#X509_CertExpiresOn) [X509_CertIsValidNow](#X509_CertIsValidNow) [X509_QueryCert](#X509_QueryCert) [[Contents](#topofpage)] [[Index](#index)] X509_CertIssuerName --------------------------------------------------- Extracts issuer's distinguished name from X.509 certificate. ### VBA/VB6 Syntax `Public Declare Function X509_CertIssuerName Lib "diCrPKI.dll" (ByVal strCertFile As String, ByVal strOutput As String, ByVal nOutChars As Long, ByVal strDelim As String, ByVal nOptions As Long) As Long` `nRet = X509_CertIssuerName(strCertFile, strOutput, nOutChars, strDelim, nOptions)` ### C/C++ Syntax `long __stdcall X509_CertIssuerName(const char *szCertFile, char *szOutput, long nOutChars, const char *szDelim, long nOptions);` ### Parameters *szCertFile* : [in] with the filename of the X.509 certificate (or [base64 representation](#base64forcert)). *szOutput* : [out] to receive the name string. *nOutChars* : [in] specifying the maximum number of characters to be received. *szDelim* : [in] specifying the character to use as a delimiter (default ";"). *nOptions* : [in] Option flags. Select one of: `PKI_DEFAULT` (0) (default) `PKI_X509_LDAP` to output the [LDAP string representation](#ldapstring) as per RFC 4514 `PKI_X509_LATIN1` to try and convert Unicode/UTF-8/T.61 attribute strings to Latin-1 (8-bit ASCII) ### Returns (VBA/C) Returns the number of characters set in *szOutput*. If *nOutChars* is zero it returns the maximum number of characters required. C/C++ users should allocate one extra for the terminating NUL character. If an error occurs, it returns a negative [error code](#errorcodes). The output using the `PKI_X509_LDAP` option is suitable as content for an `` node in an XML-DSIG document. ### .NET Equivalent [X509.CertIssuerName Method](#M_X509_CertIssuerName) ### Remarks See the remarks for [`X509_CertSubjectName()`](#X509_CertSubjectName). ### Example See [`X509_CertSubjectName`](#X509_CertSubjectName). ### See Also [X509_CertIssuerName](#X509_CertSubjectName) [X509_HashIssuerAndSN](#X509_HashIssuerAndSN) [X509_QueryCert](#X509_QueryCert) [[Contents](#topofpage)] [[Index](#index)] X509_CertIsValidNow --------------------------------------------------- Verifies that an X.509 certificate is currently valid. ### VBA/VB6 Syntax `Public Declare Function X509_CertIsValidNow Lib "diCrPKI.dll" (ByVal strCertFile As String, ByVal nOptions As Long) As Long` `nRet = X509_CertIsValidNow(strCertFile, nOptions)` ### C/C++ Syntax `long __stdcall X509_CertIsValidNow(const char *szCertFile, long nOptions);` ### Parameters *szCertFile* : [in] with the filename of the certificate (or [base64 representation](#base64forcert)). *nOptions* : [in] option flags: not used in this release. Specify zero. ### Returns (VBA/C) Zero (0) if the certificate is valid at the current time. If the certificate has expired or is not yet valid, the return value is `PKI_X509_EXPIRED` (+16 = `EXPIRED_ERROR`); otherwise it returns a *positive* [error code](#errorcodes). ### .NET Equivalent [X509.CertIsValidNow Method](#M_X509_CertIsValidNow) ### C++ (STL) Equivalent static bool [dipki::X509::CertIsValidNow](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_x509.html#ac6ef066faf9ca7d9c4e5b7d7d5a04973 "External link") (const std::string &certFile) ### Python Equivalent static [X509.cert_is_valid_now](https://cryptosys.net/pki/pydocpki/class-stubs/X509.html#cryptosyspki.X509.cert_is_valid_now "External link")(certfile) ### Remarks Note that the return value for "success" is zero, not "true". Uses the system clock. The certificate may be in binary DER format or base64 PEM format. *[Changed in v12.0]* If the certificate is otherwise of correct format but has expired or is not yet valid, this function returns `EXPIRED_ERROR` (16). Previous versions would return -1. ### Example ``` Dim nRet As Long Dim strCertName As String strCertName = "myca.cer" nRet = X509_CertIsValidNow(strCertName, 0) Debug.Print "X509_CertIsValidNow returns " & nRet & " for " & strCertName ``` ### See Also [X509_VerifyCert](#X509_VerifyCert) [X509_ValidatePath](#X509_ValidatePath) [X509_CertThumb](#X509_CertThumb) [[Contents](#topofpage)] [[Index](#index)] X509_CertRequest --------------------------------------------- Creates a PKCS #10 certificate signing request (CSR) using the subject's private key file. ### VBA/VB6 Syntax `Public Declare Function X509_CertRequest Lib "diCrPKI.dll" (ByVal strReqFile As String, ByVal strPriKeyFile As String, ByVal strDistName As String, ByVal strExtensions As String, ByVal strPassword As String, ByVal nOptions As Long) As Long` `nRet = X509_CertRequest(strReqFile, strPriKeyFile, strDistName, strExtensions, strPassword, nOptions)` ### C/C++ Syntax `long __stdcall X509_CertRequest(const char *szNewReqFile, const char *szPriKeyFile, const char *szDistName, const char *szExtensions, const char *szPassword, long nOptions);` ### Parameters *szNewReqFile* : [in] Name of new certificate request file to be created. *szPriKeyFile* : [in] Name of subject's private key file (encrypted or unencrypted) or a [PEM string](#pemstring) containing the key. *szDistName* : [in] Distinguished name string. See [Specifying Distinguished Names](#distnames) for more details. *szExtensions* : [in] (optional) Extensions: a list of attribute-value pairs separated by semicolons (;) to be added to an `extensionRequest` element. See [X.509 Extensions Parameter](#x509extensions). *[New in v10.0]*. *szPassword* : [in] Password for subject's encrypted private key file. Specify the empty string `""` if key not encrypted *[New in v12.0]*. *nOptions* : [in] Option flags. Choose one signature algorithm from: `PKI_SIG_SHA1RSA` (0) to use `sha1WithRSAEncryption` (default - CAUTION) `PKI_SIG_SHA224RSA` to use `sha224WithRSAEncryption` `PKI_SIG_SHA256RSA` to use `sha256WithRSAEncryption` [minimum recommended] `PKI_SIG_SHA384RSA` to use `sha384WithRSAEncryption` `PKI_SIG_SHA512RSA` to use `sha512WithRSAEncryption` `PKI_SIG_MD5RSA` to use `md5WithRSAEncryption` [legacy, not recommended] `PKI_SIG_MD2RSA` to use `md2WithRSAEncryption` [legacy, definitely not recommended] `PKI_SIG_RSA_PSS_SHA1` to use `RSA-PSS-SHA1` `PKI_SIG_RSA_PSS_SHA224` to use `RSA-PSS-SHA224` `PKI_SIG_RSA_PSS_SHA256` to use `RSA-PSS-SHA256` `PKI_SIG_RSA_PSS_SHA384` to use `RSA-PSS-SHA384` `PKI_SIG_RSA_PSS_SHA512` to use `RSA-PSS-SHA512` `PKI_SIG_ECDSA_SHA1` to use `ecdsaWithSHA1` `PKI_SIG_ECDSA_SHA224` to use `ecdsaWithSHA224` `PKI_SIG_ECDSA_SHA256` to use `ecdsaWithSHA256` `PKI_SIG_ECDSA_SHA384` to use `ecdsaWithSHA384` `PKI_SIG_ECDSA_SHA512` to use `ecdsaWithSHA512` `PKI_SIG_ED25519` to use `Ed25519` *[New in v20.0]* `PKI_SIG_ED448` to use `Ed448` *[New in v22.0]* And add any combination of these:- `PKI_X509_FORMAT_BIN` to create a BER-encoded binary file (default = base64 PEM format) `PKI_X509_REQ_KLUDGE` to create a request with the "kludge" that omits the strictly mandatory attributes completely (default = include attributes with zero-length field) `PKI_X509_UTF8` to encode the DN as `UTF8String` (default = PrintableString) Specialist options:- `PKI_PSS_SALTLEN_ZERO` to use a zero-length salt in an RSA-PSS signature. `PKI_SIG_DETERMINISTIC` to use the deterministic digital signature generation procedure of [[RFC6979](#RFC6979)] for an ECDSA signature. ### Returns (VBA/C) If successful, the return value is zero; otherwise it returns a nonzero [error code](#errorcodes). ### .NET Equivalent [X509.CertRequest Method](#M_X509_CertRequest) ### C++ (STL) Equivalent static int [dipki::X509::CertRequest](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_x509.html#af0c4852b7eb96fe4be27dbb5eb738855 "External link") (const std::string &newFile, const std::string &priKeyFile, const std::string &password, const std::string distName, const std::string extns="", SigAlg sigAlg=SigAlg::Default, CsrOptions opts=CsrOptions::Default_CsrOpt) ### Python Equivalent static [X509.cert_request](https://cryptosys.net/pki/pydocpki/class-stubs/X509.html#cryptosyspki.X509.cert_request "External link")(newcsrfile, prikeyfile, password, distname, extns="", sigalg=0, opts=0) ### Remarks The default output is a base64 PEM format CSR file ready for sending to the issuer of your choice. Any existing file of the same name will be overwritten without warning. ### Example This example will create a new certificate request with filename `myreq.p10.txt`. for the subject with common name "myuser", etc. The subject's encrypted private key is in the file `mykey.p8e` and has the password "password". The certificate request will be signed using the subject's private key using the default `sha1WithRSAEncryption` algorithm. ``` Dim nRet As Long nRet = X509_CertRequest("myreq.p10.txt", "mykey.p8e", _ "CN=myuser;O=Test Org;C=AU;L=Sydney;S=NSW", "", "password", 0) If nRet <> 0 Then Debug.Print nRet & " " & pkiGetLastError() Else Debug.Print "Success" End If ``` This should produce an output file similar to: ``` -----BEGIN CERTIFICATE REQUEST----- MIIBGjCBxQIBADBQMQ8wDQYDVQQDEwZteXVzZXIxETAPBgNVBAoTCFRlc3QgT3Jn MQswCQYDVQQGEwJBVTEPMA0GA1UECBMGU3lkbmV5MQwwCgYDVQQHEwNOU1cwWjAN BgkqhkiG9w0BAQEFAANJADBGAkEAvdci5sKarpPzljBVVxJfGEfBOvjxlgFYOg1x xEEG9Xbilxgl3kTfIrA4KqNmGdEKPksbHXNuxXkwaaAld3bBHQIBA6ASMBAGCisG AQQBgjcCAQ4xAjAAMA0GCSqGSIb3DQEBBQUAA0EAtqie6G31yRcwJljEDdbeYd+w 5FvLd631nL//JuISFv6fl9B30WtHQtI1wuryVYZ6fRWZPpu9jZjs5gsnKFtiUg== -----END CERTIFICATE REQUEST----- ``` The next example duplicates the certificate request in Sections 3.1 to 3.3 of "Some Examples of the PKCS Standards" [[PKCS-EX](#PKCS-EX)]. It uses the 508-bit private key to sign the request, which is stored in the file `rsa508.p8e` with the password "password". The signature algorithm is `md2WithRSAEncryption` and the output is in binary format. To reproduce this example requires the non-strict "kludge". The output should exactly match the CertificationRequest value in section 3.2 of PKCS-EX. ``` Dim nRet As Long nRet = X509_CertRequest("pkcs_ex_req.bin", "rsa508.p8e", _ "C=US;O=Example Organization;CN=Test User 1", "", "password", _ PKI_SIG_MD2RSA + PKI_X509_FORMAT_BIN + PKI_X509_REQ_KLUDGE) If nRet <> 0 Then Debug.Print nRet & " " & pkiGetLastError() Else Debug.Print "Success" End If ``` The latter example is just to demonstrate the replication of an old but known test vector, not to demonstrate good practice. ### See Also [X509_MakeCert](#X509_MakeCert) [[Contents](#topofpage)] [[Index](#index)] X509_CertSerialNumber ------------------------------------------------------- Returns the serial number of an X.509 certificate. ### VBA/VB6 Syntax `Public Declare Function X509_CertSerialNumber Lib "diCrPKI.dll" (ByVal strCertFile As String, ByVal strOutput As String, ByVal nOutChars As Long, ByVal nOptions As Long) As Long` `nRet = X509_CertSerialNumber(strCertFile, strOutput, nOutChars, nOptions)` ### C/C++ Syntax `long __stdcall X509_CertSerialNumber(const char *szCertFile, char *szOutput, long nOutChars, long nOptions);` ### Parameters *szCertFile* : [in] with the filename of the X.509 certificate (or [base64 representation](#base64forcert)). *szOutput* : [out] to receive the serial number. *nOutChars* : [in] specifying the maximum number of characters to be received. *nOptions* : [in] option flags: `PKI_DEFAULT` (0) for default output in hexadecimal format `PKI_X509_DECIMAL` to output number in decimal format ### Returns (VBA/C) Returns the number of characters set in *szOutput*. If *nOutChars* is zero it returns the maximum number of characters required. C/C++ users should allocate one extra for the terminating NUL character. If an error occurs, it returns a negative [error code](#errorcodes). ### .NET Equivalent [X509.CertSerialNumber Method](#M_X509_CertSerialNumber) ### Remarks The certificate may be in binary DER format or base64 PEM format. ### Example ``` Dim nRet As Long Dim strCertName As String Dim strOutput As String * 64 strCertName = "BobRSASignByCarl.cer" ' Set dir to suit nRet = X509_CertSerialNumber(strCertName, strOutput, Len(strOutput), 0) Debug.Print "X509_CertSerialNumber returns " & nRet & " for " & strCertName & ": " & Left(strOutput, nRet) ``` Should result in ``` X509_CertSerialNumber returns 32 for BobRSASignByCarl.cer: 46346bc7800056bc11d36e2ecd5d71d0 ``` ### See Also [X509_CertIsValidNow](#X509_CertIsValidNow) [X509_CertThumb](#X509_CertThumb) [[Contents](#topofpage)] [[Index](#index)] X509_CertSubjectName ----------------------------------------------------- Extracts subject's distinguished name from X.509 certificate. ### VBA/VB6 Syntax `Public Declare Function X509_CertSubjectName Lib "diCrPKI.dll" (ByVal strCertFile As String, ByVal strOutput As String, ByVal nOutChars As Long, ByVal strDelim As String, ByVal nOptions As Long) As Long` `nRet = X509_CertSubjectName(strCertFile, strOutput, nOutChars, strDelim, nOptions)` ### C/C++ Syntax `long __stdcall X509_CertSubjectName(const char *szCertFile, char *szOutput, long nOutChars, const char *szDelim, long nOptions);` ### Parameters *szCertFile* : [in] with the filename of the X.509 certificate (or [base64 representation](#base64forcert)). *szOutput* : [out] to receive the name string. *nOutChars* : [in] specifying the maximum number of characters to be received. *szDelim* : [in] specifying the character to use as a delimiter (default ";"). *nOptions* : [in] Option flags. `PKI_DEFAULT` (0) (default) `PKI_X509_LDAP` to output the [LDAP string representation](#ldapstring) as per RFC 4514 `PKI_X509_LATIN1` to try and convert Unicode/UTF-8/T.61 attribute strings to Latin-1 (8-bit ASCII) ### Returns (VBA/C) Returns the number of characters set in *szOutput*. If *nOutChars* is zero it returns the maximum number of characters required. C/C++ users should allocate one extra for the terminating NUL character. If an error occurs, it returns a negative [error code](#errorcodes). ### .NET Equivalent [X509.CertSubjectName Method](#M_X509_CertSubjectName) ### Remarks The distinguished name will be returned in a string expressed in the same format described in [Distinguished Names](#distnames), e.g. `"C=AU;O=myorg;CN=Dave"`. Only the first character in *szDelim* is used. The default delimiter is a semi-colon (;) if an empty string or NULL is specified for *szDelim*. If the attribute key is not in our set of [supported types](#dnsupportedtype), the OID will be expressed in dot notation, e.g. `"2.5.4.4=My Surname"`. If an attribute value is encoded in a multi-byte-character string format (such as UTF8String or BMPString), the value will be expressed as a hexadecimal-encoded string *[NB changed in v3.9]* preceded by the hash symbol (`'#'` U+0023) and small letter x (`'x'` U+0078), e.g. ``` "C=TW;O=E8 A1 8C E6 94 BF E9 99 A2" (v3.8 and earlier) "C=TW;O=#xE8A18CE694BFE999A2" (v3.9 and later) ``` Use the `PKI_X509_LATIN1` option to return the string encoded in Latin-1, if possible, so it will display properly on systems that cannot cope with UTF-8. *[New in v3.9]* Use the `PKI_X509_LDAP` option to obtain the distinguished name in LDAP string form instead. The examples above would be returned as `"CN=Dave,O=myorg,C=AU"` and `"O=\E8\A1\8C\E6\94\BF\E9\99\A2,C=TW"`, with commas as delimiters, the RDNs in reverse order, and non-printable-ASCII characters escaped in hexadecimal form "\xx" as per [[RFC4514](#RFC4514)]. See [LDAP string representation](#ldapstring) for more details. The *szDelim* parameter is ignored with the `PKI_X509_LDAP` option. The output using the `PKI_X509_LDAP` option is suitable as content for an `` node in an XML-DSIG document. ### Example ``` Dim nRet As Long Dim nLen As Long Dim strCertName As String Dim strOutput As String strCertName = "dai.cer" nLen = X509_CertIssuerName(strCertName, "", 0, ";", 0) Debug.Print "X509_CertIssuerName returns " & nLen & " for " & strCertName strOutput = String(nLen, " ") nRet = X509_CertIssuerName(strCertName, strOutput, Len(strOutput), ";", 0) Debug.Print "[" & strOutput & "]" ' Example outputting in LDAP format nLen = X509_CertIssuerName(strCertName, "", 0, "", PKI_X509_LDAP) Debug.Print "X509_CertIssuerName(LDAP) returns " & nLen & " for " & strCertName strOutput = String(nLen, " ") nRet = X509_CertIssuerName(strCertName, strOutput, Len(strOutput), "", PKI_X509_LDAP) Debug.Print "[" & strOutput & "]" nLen = X509_CertSubjectName(strCertName, "", 0, ";", 0) Debug.Print "X509_CertSubjectName returns " & nLen & " for " & strCertName strOutput = String(nLen, " ") nRet = X509_CertSubjectName(strCertName, strOutput, Len(strOutput), ",", 0) Debug.Print "[" & strOutput & "]" ' Example outputting in LDAP format nLen = X509_CertSubjectName(strCertName, "", 0, "", PKI_X509_LDAP) Debug.Print "X509_CertSubjectName(LDAP) returns " & nLen & " for " & strCertName strOutput = String(nLen, " ") nRet = X509_CertSubjectName(strCertName, strOutput, Len(strOutput), "", PKI_X509_LDAP) Debug.Print "[" & strOutput & "]" ``` This example is for an old Thawte personal certificate. The output is as follows: ``` X509_CertIssuerName returns 100 for dai.cer [C=ZA;ST=Western Cape;L=Cape Town;O=Thawte;OU=Certificate Services;CN=Personal Freemail RSA 2000.8.30] X509_CertIssuerName(LDAP) returns 100 for dai.cer [CN=Personal Freemail RSA 2000.8.30,OU=Certificate Services,O=Thawte,L=Cape Town,ST=Western Cape,C=ZA] X509_CertSubjectName returns 76 for dai.cer [SN=Ireland,G=David Alexander,CN=David Alexander Ireland,E=code@di-mgt.com.au] X509_CertSubjectName(LDAP) returns 107 for dai.cer [1.2.840.113549.1.9.1=code@di-mgt.com.au,CN=David Alexander Ireland,2.5.4.42=David Alexander,2.5.4.4=Ireland] ``` ### See Also [X509_CertIssuerName](#X509_CertIssuerName) [X509_HashIssuerAndSN](#X509_HashIssuerAndSN) [X509_QueryCert](#X509_QueryCert) [[Contents](#topofpage)] [[Index](#index)] X509_CertThumb ----------------------------------------- Calculates the thumbprint (message digest hash) of an X.509 certificate. ### VBA/VB6 Syntax `Public Declare Function X509_CertThumb Lib "diCrPKI.dll" (ByVal strCertFile As String, ByVal strHexHash As String, ByVal nHexHashLen As Long, ByVal nOptions As Long) As Long` `nRet = X509_CertThumb(strCertFile, strHexHash, nHexHashLen, nOptions)` ### C/C++ Syntax `long __stdcall X509_CertThumb(const char *szCertFile, char *szOutput, long nOutChars, long nOptions);` ### Parameters *szCertFile* : [in] with the filename of the X.509 certificate (or [base64 representation](#base64forcert)). *szOutput* : [out] to receive the message digest. *nOutChars* : [in] specifying the maximum length of the digest string. *nOptions* : [in] Option flags. Select one of: `PKI_HASH_SHA1` (0) to use the SHA-1 algorithm (default) `PKI_HASH_SHA224` to use the SHA-224 algorithm `PKI_HASH_SHA256` to use the SHA-256 algorithm `PKI_HASH_SHA384` to use the SHA-384 algorithm `PKI_HASH_SHA512` to use the SHA-512 algorithm `PKI_HASH_MD5` to use the MD5 algorithm ### Returns (VBA/C) the number of digits set in the output string or a negative [error code](#errorcodes). ### VBA Wrapper Syntax Public Function [`x509CertThumb`](#VB_x509CertThumb) (szCertFile As String, Optional nOptions As Long = 0) As String ### .NET Equivalent [X509.CertThumb Method](#M_X509_CertThumb) ### C++ (STL) Equivalent static std::string [dipki::X509::CertThumb](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_x509.html#a42640b33c3c4c2745644b2c3f067ed21 "External link") (const std::string &certFile, HashAlg hashAlg=HashAlg::Sha1) ### Python Equivalent static [X509.cert_thumb](https://cryptosys.net/pki/pydocpki/class-stubs/X509.html#cryptosyspki.X509.cert_thumb "External link")(certfilename, hashalg=0) ### Remarks For the "raw" VBA/C function, the user must allocate an output string buffer *szOutput* of the required length. Specify a zero *nOutChars* or an empty string for *szOutput* to find the required length. ANSI C users [must add one to this value](#cusersaddone) when allocating memory. The maximum length of the output string is `PKI_MAX_HASH_CHARS` (C/C++ users add one). The default hash algorithm is SHA-1 and the result should match the SHA-1 thumbprint shown in the Windows Certificate Viewer. ### Example (VBA core function) These examples compute the SHA-1 message digest hash ("thumbprint") of Alice's certificate from S/MIME examples. ``` Dim nRet As Long Dim strCertName As String Dim strHexHash As String strHexHash = String(PKI_SHA1_CHARS, " ") strCertName = "AliceRSASignByCarl.cer" nRet = X509_CertThumb(strCertName, strHexHash, Len(strHexHash), 0) Debug.Print "X509_CertThumb returns " & nRet & " for " & strCertName Debug.Print strHexHash ``` In C: ``` long lRet; char *certname = "C:\\test\\AliceRSASignByCarl.cer"; char hexdigest[PKI_SHA1_CHARS+1]; /* NB one extra */ lRet = X509_CertThumb(certname, hexdigest, sizeof(hexdigest)-1, 0); printf("X509_CertThumb returns %ld for %s\n", lRet, certname); printf("%s\n", hexdigest); ``` Both of these should result in ``` X509_CertThumb returns 40 for AliceRSASignByCarl.cer b30c48855055c2e64ce3196492d4b83831a6b3cb ``` ### Example (VBA wrapper function) ``` Dim strCertString As String strCertString = x509ReadStringFromFile("AliceRSASignByCarl.cer") Debug.Print strCertString Debug.Print "CertThumb=" & x509CertThumb(strCertString) strCertString = x509ReadCertStringFromP7Chain("alice_bob_carl_certs.p7c", 3) Debug.Print strCertString Debug.Print "CertThumb=" & x509CertThumb(strCertString) Debug.Print "HashIssuerAndSN=" & x509HashIssuerAndSN(strCertString, PKI_HASH_SHA256) ``` ### See Also [X509_CertIsValidNow](#X509_CertIsValidNow) [X509_VerifyCert](#X509_VerifyCert) [[Contents](#topofpage)] [[Index](#index)] X509_CheckCertInCRL --------------------------------------------------- Checks whether an X.509 certificate has been revoked in a Certificate Revocation List (CRL). ### VBA/VB6 Syntax `Public Declare Function X509_CheckCertInCRL Lib "diCrPKI.dll" (ByVal strCertFile As String, ByVal strCrlFile As String, ByVal strCRLIssuerCert As String, ByVal strDate As String, ByVal nOptions As Long) As Long` `nRet = X509_CheckCertInCRL(strCertFile, strCrlFile, strCRLIssuerCert, strDate, nOptions)` ### C/C++ Syntax `long __stdcall X509_CheckCertInCRL(const char *szCertFile, const char *szCrlFile, const char *szCRLIssuerCert, const char *szDate, long nOptions);` ### Parameters *szCertFile* : [in] with name of X.509 certificate to be checked (or [base64 representation](#base64forcert)). *szCrlFile* : [in] with name of CRL file. *szCRLIssuerCert* : [in] (optional) with name of X.509 certificate file for the entity that issued the CRL (or [base64 representation](#base64forcert)). *szDate* : [in] (optional) with date in [ISO date format](#iso8601datetime) (e.g. `2009-12-31T12:59:59Z`) on or after you wish to check for revocation. Leave empty `""` for any date. The time *must* be in GMT (UTC, Zulu time). *nOptions* : [in] Option flags. Not used. Specify zero. ### Returns (VBA/C) Zero (0) if the certificate is not in the CRL (i.e has not been revoked by that particular CRL). If the certificate has been revoked it returns `PKI_X509_REVOKED` (+42=`REVOCATION_ERROR`); otherwise a *negative* [error code](#errorcodes). ### .NET Equivalent [X509.CheckCertInCRL Method](#M_X509_CheckCertInCRL) ### Python Equivalent static [X509.cert_is_revoked](https://cryptosys.net/pki/pydocpki/class-stubs/X509.html#cryptosyspki.X509.cert_is_revoked "External link")(certfile, crlfile, crl_issuercert="", isodate="") ### Remarks The optional *szDate* parameter allows you to check whether a certificate was revoked only after the given date-time, which **must** be in GMT (UTC). If the optional *szCRLIssuerCert* is specified, the signature of the CRL will be checked against the key in the issuer's certificate and a `SIGNATURE_ERROR` will result if the signature is invalid. You can directly verify the signature in the CRL file using the [X509_VerifyCert()](#X509_VerifyCert) function. *[Changed in v12.0]* If the certificate is otherwise of correct format but has been revoked, this function returns `REVOCATION_ERROR` (42). Previous versions would return +1. ### Example ``` Dim nRet As Long Dim strCrlFile As String Dim strCertFile As String Dim strDate As String ' Use test CRL and certs from RFC3280 strCrlFile = "rfc3280bis_CRL.crl" ' This cert has not been revoked. strCertFile = "rfc3280bis_cert1.cer" Debug.Print "CrlFile=" & strCrlFile Debug.Print "CertFile=" & strCertFile nRet = X509_CheckCertInCRL(strCertFile, strCrlFile, "", "", 0) Debug.Print "X509_CheckCertInCRL returns " & nRet If nRet = PKI_X509_REVOKED Then Debug.Print "CERT HAS BEEN REVOKED" ElseIf nRet = 0 Then Debug.Print "Cert has not been revoked" Else Debug.Print "ERROR: " & pkiErrorLookup(nRet) & ": " & pkiGetLastError() End If ' This cert has been revoked. strCertFile = "rfc3280bis_cert2.cer" Debug.Print "CrlFile=" & strCrlFile Debug.Print "CertFile=" & strCertFile nRet = X509_CheckCertInCRL(strCertFile, strCrlFile, "", "", 0) Debug.Print "X509_CheckCertInCRL returns " & nRet If nRet = PKI_X509_REVOKED Then Debug.Print "CERT HAS BEEN REVOKED" ElseIf nRet = 0 Then Debug.Print "Cert has not been revoked" Else Debug.Print "ERROR: " & pkiErrorLookup(nRet) & ": " & pkiGetLastError() End If ' But the same cert was not revoked as at 15:00 GMT on 19 November 2004 strCertFile = "rfc3280bis_cert2.cer" strDate = "2004-11-19T15:00Z" Debug.Print "CrlFile=" & strCrlFile Debug.Print "CertFile=" & strCertFile Debug.Print "Date=" & strDate nRet = X509_CheckCertInCRL(strCertFile, strCrlFile, "", strDate, 0) Debug.Print "X509_CheckCertInCRL(" & strDate & ") returns " & nRet If nRet = PKI_X509_REVOKED Then Debug.Print "CERT HAS BEEN REVOKED" ElseIf nRet = 0 Then Debug.Print "Cert has not been revoked" Else Debug.Print "ERROR: " & pkiErrorLookup(nRet) & ": " & pkiGetLastError() End If ``` This code should produce the following output ``` CrlFile=rfc3280bis_CRL.crl CertFile=rfc3280bis_cert1.cer X509_CheckCertInCRL returns 0 Cert has not been revoked CrlFile=rfc3280bis_CRL.crl CertFile=rfc3280bis_cert2.cer X509_CheckCertInCRL returns 1 CERT HAS BEEN REVOKED CrlFile=rfc3280bis_CRL.crl CertFile=rfc3280bis_cert2.cer Date=2004-11-19T15:00Z X509_CheckCertInCRL(2004-11-19T15:00Z) returns 0 Cert has not been revoked ``` ### See Also [X509_MakeCRL](#X509_MakeCRL) [X509_VerifyCert](#X509_VerifyCert) [X509_CertIsValidNow](#X509_CertIsValidNow) [X509_ValidatePath](#X509_ValidatePath) [[Contents](#topofpage)] [[Index](#index)] X509_GetCertCountInP7Chain ----------------------------------------------------------------- Return number of certificates in a PKCS-7 "certs-only" certificate chain file. ### VBA/VB6 Syntax `Public Declare Function X509_GetCertCountInP7Chain Lib "diCrPKI.dll" (ByVal strP7cFile As String, ByVal nOptions As Long) As Long` `nRet = X509_GetCertCountInP7Chain(strP7cFile, nOptions) As Long` ### C/C++ Syntax `long __stdcall X509_GetCertCountInP7Chain(const char *szP7cFile, long nOptions);` ### Parameters *szP7cFile* : [in] filename of the PKCS-7 "certs-only" file, or a string containing its [PEM textual representation](#pemstring). *nOptions* : [in] option flags: not used in this release. Specify zero. ### Returns (VBA/C) Number of X.509 certificates found or a negative [error code](#errorcodes). ### .NET Equivalent [X509.GetCertCountInP7Chain Method](#M_X509_GetCertCountInP7Chain) ### C++ (STL) Equivalent static int [dipki::X509::GetCertCountInP7Chain](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_x509.html#ab39028867279fae0db82bd281caedbc1 "External link") (const std::string &inputFile) ### Python Equivalent static [X509.get_cert_count_from_p7](https://cryptosys.net/pki/pydocpki/class-stubs/X509.html#cryptosyspki.X509.get_cert_count_from_p7 "External link")(p7file) ### Remarks This function will also work with CMS signed data objects, too. ### Example ``` nCerts = X509_GetCertCountInP7Chain("certs.p7c", 0) ``` will return the number of certificates found in the file `certs.p7c`. ### See Also [X509_GetCertFromP7Chain](#X509_GetCertFromP7Chain) [X509_ReadCertStringFromP7Chain](#X509_ReadCertStringFromP7Chain) [CMS_QuerySigData](#CMS_QuerySigData) [[Contents](#topofpage)] [[Index](#index)] X509_GetCertFromP7Chain ----------------------------------------------------------- Extracts an X.509 certificate from a PKCS-7 "certs-only" certificate chain file (typically saved with extension `.p7c` or `.p7b`), saving the output directly as a new file. ### VBA/VB6 Syntax `Public Declare Function X509_GetCertFromP7Chain Lib "diCrPKI.dll" (ByVal strOutputFile As String, ByVal strP7cFile As String, ByVal nIndex As Long, ByVal nOptions As Long) As Long` `nRet = X509_GetCertFromP7Chain(strOutputFile, strP7cFile, nIndex, nOptions) As Long` ### C/C++ Syntax `long __stdcall X509_GetCertFromP7Chain(const char *szNewCertFile, const char *szP7cFile, long nIndex, long nOptions);` ### Parameters *szNewCertFile* : [in] filename of the output file to be created. *szP7cFile* : [in] filename of the PKCS-7 "certs-only" file, or a string containing its [PEM textual representation](#pemstring). *nIndex* : [in] specifying which certificate (1,2,...) in the chain to extract, or 0 (deprecated) to return the count of certificates in the set. *nOptions* : [in] option flags: not used in this release. Specify zero. ### Returns (VBA/C) If successful and *nIndex* is greater than zero, it returns the number of bytes written to the output file, which may be zero if no certificate could be found at the given index. If an error occurred, it returns a negative [error code](#errorcodes). ### .NET Equivalent [X509.GetCertFromP7Chain Method](#M_X509_GetCertFromP7Chain) ### C++ (STL) Equivalent static bool [dipki::X509::GetCertFromP7Chain](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_x509.html#a08efea2f2eb7412bdbc0c47c9af25341 "External link") (const std::string &outputFile, const std::string &inputFile, int index) ### Python Equivalent static [X509.get_cert_from_p7](https://cryptosys.net/pki/pydocpki/class-stubs/X509.html#cryptosyspki.X509.get_cert_from_p7 "External link")(outfile, p7file, index=1) ### Remarks If *nIndex* is specified as a number greater than zero, the *nIndex*'th certificate found in the list, if any, will be extracted and saved directly as a DER-encoded X.509 certificate file. This function will also extract certificates from CMS signed data objects, too. *[New in v12.2]* To find the number of certificates in the chain, use [X509_GetCertCountInP7Chain](#X509_GetCertCountInP7Chain). The old (deprecated) way to find the count of certificates was to set *nIndex* to zero. ### Example ``` nBytes = X509_GetCertFromP7Chain("cert2.cer", "certs.p7c", 2, 0) ``` will extract the second certificate in `certs.p7c` and create a new X.509 certificate file called `cert2.cer` containing `nBytes` bytes. The following example shows how to extract all the certificates from a PKCS-7 CertList file ``` Dim nRet As Long Dim strListFile As String Dim strCertFile As String Dim nCerts As Long Dim iCert As Long strListFile = "bob.p7b" ' How many certificates? - NB new function in [v12.2] nCerts = X509_GetCertCountInP7Chain(strListFile, 0) Debug.Print "X509_GetCertCountInP7Chain returns " & nCerts & " for " & strListFile ' Enumerate through them all If nCerts > 0 Then For iCert = 1 To nCerts strCertFile = "bobcert" & iCert & ".cer" nRet = X509_GetCertFromP7Chain(strCertFile, strListFile, iCert, 0) Debug.Print "X509_GetCertFromP7Chain(" & iCert & ") returns " _ & nRet & "->" & strCertFile Next End If ``` This should result in output as follows: ``` X509_GetCertCountInP7Chain() returns 2 for bob.p7b X509_GetCertFromP7Chain(1) returns 555->bobcert1.cer X509_GetCertFromP7Chain(2) returns 495->bobcert2.cer ``` where, in this example, the file `bob.p7b` contains two X.509 certificates of size 555 and 495 bytes respectively. ### See Also [X509_ReadCertStringFromP7Chain](#X509_ReadCertStringFromP7Chain) [X509_GetCertCountInP7Chain](#X509_GetCertCountInP7Chain) [CMS_QuerySigData](#CMS_QuerySigData) [[Contents](#topofpage)] [[Index](#index)] X509_GetCertFromPFX --------------------------------------------------- Extracts an X.509 certificate from a PKCS-12 PFX/.p12 file, saving the output directly as a new file. ### VBA/VB6 Syntax `Public Declare Function X509_GetCertFromPFX Lib "diCrPKI.dll" (ByVal strOutputFile As String, ByVal strPfxFile As String, ByVal strPassword As String, ByVal nOptions As Long) As Long` `nRet = X509_GetCertFromPFX(strOutputFile, strPfxFile, strPassword, nOptions) As Long` ### C/C++ Syntax `long __stdcall X509_GetCertFromPFX(const char *szNewCertFile, const char *szPfxFile, const char *szPassword, long nOptions);` ### Parameters *szNewCertFile* : [in] specifying the filename of the output file to be created. *szPfxFile* : [in] containing the PFX filename *szPassword* : [in] containing password or `""` if certificate is not encrypted *nOptions* : [in] option flags: `PKI_DEFAULT` (0) to export a single DER-encoded X.509 certificate. `PKI_PFX_P7CHAIN` to output all certificates in a PKCS7 certificate chain file (`.p7b` or `.p7c`). ### Returns (VBA/C) If successful, it returns the number of bytes written to the output file; otherwise it returns a negative [error code](#errorcodes). ### .NET Equivalent [X509.GetCertFromPFX Method](#M_X509_GetCertFromPFX) [X509.GetP7ChainFromPFX Method](#M_X509_GetP7ChainFromPFX) ### C++ (STL) Equivalent static bool [dipki::X509::GetCertFromPFX](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_x509.html#a203c6c2df25242677aed1b245d945bfa "External link") (const std::string &outputFile, const std::string &inputFile, const std::string &password) static [X509.get_p7chain_from_pfx](https://cryptosys.net/pki/pydocpki/class-stubs/X509.html#cryptosyspki.X509.get_p7chain_from_pfx "External link")(outfile, pfxfile, password) ### Python Equivalent `static [X509.get_cert_from_pfx](https://cryptosys.net/pki/pydocpki/class-stubs/X509.html#cryptosyspki.X509.get_cert_from_pfx "External link")(outfile, pfxfile, password)` static [X509.get_p7chain_from_pfx](https://cryptosys.net/pki/pydocpki/class-stubs/X509.html#cryptosyspki.X509.get_p7chain_from_pfx "External link")(outfile, pfxfile, password) ### Remarks The default behaviour is to extract one certificate from the PFX file and save directly as a DER-encoded X.509 certificate file. Any existing file of the same name will be overwritten without warning. It will attempt to find a matching certificate for any private key, otherwise it will save the first `pkcs-12-certBag` found in the PFX file containing a `x509Certificate`. Both unencrypted certificates and certificates encrypted with the weak 40-bit encryption used by "default" in Microsoft and OpenSSL PKCS-12 files are supported, but not any other encryption algorithm. If no certificate can be found the function will return a negative `NO_DATA_ERROR` error code. The `PKI_PFX_P7CHAIN` option will output all X.509 certificates found into a single PKCS#7 certificate chain file. The correct MIME-designated file extension for such a file is `.p7c`, but for historical reasons Microsoft use `.p7b` instead. ### Example ``` nChars = X509_GetCertFromPFX("mycert.cer", "mypkcs12file.pfx", "password", 0) ``` will extract an X.509 certificate from the PKCS-12 file `mypkcs12file.pfx` with password "password", and save it as the new DER-encoded certificate file `mycert.cer`. The variable *nChars* will contain the size in bytes of the new file it created, or a negative error code. ### See Also [X509_ReadCertStringFromPFX](#X509_ReadCertStringFromPFX) [PFX_VerifySig](#PFX_VerifySig) [[Contents](#topofpage)] [[Index](#index)] X509_HashIssuerAndSN ----------------------------------------------------- Returns the message digest hash of the PKCS #7 issuerAndSerialNumber value of an X.509 certificate in hexadecimal format. ### VBA/VB6 Syntax `Public Declare Function X509_HashIssuerAndSN Lib "diCrPKI.dll" (ByVal strCertFile As String, ByVal strOutput As String, ByVal nOutChars As Long, ByVal nOptions As Long) As Long` `nRet = X509_HashIssuerAndSN(strCertFile, strOutput, nOutChars, nOptions)` ### C/C++ Syntax `long __stdcall X509_HashIssuerAndSN(const char *szCertFile, char *szOutput, long nOutChars, long nOptions);` ### Parameters *szCertFile* : [in] with the filename of the X.509 certificate (or [base64 representation](#base64forcert)). *szOutput* : [out] to receive the hash digest. *nOutChars* : [in] specifying the maximum number of characters to be received. *nOptions* : [in] Option flags. Select one of: `PKI_HASH_SHA1` (0) to use the SHA-1 algorithm (default) `PKI_HASH_SHA224` to use the SHA-224 algorithm `PKI_HASH_SHA256` to use the SHA-256 algorithm `PKI_HASH_SHA384` to use the SHA-384 algorithm `PKI_HASH_SHA512` to use the SHA-512 algorithm `PKI_HASH_MD5` to use the MD5 algorithm ### Returns (VBA/C) Returns the number of characters set in *szOutput*. If *nOutChars* is zero it returns the maximum number of characters required. C/C++ users should allocate one extra for the terminating NUL character. If an error occurs, it returns a negative [error code](#errorcodes). ### VBA Wrapper Syntax Public Function [`x509HashIssuerAndSN`](#VB_x509HashIssuerAndSN) (szCertFile As String, Optional nOptions As Long = 0) As String ### .NET Equivalent [X509.HashIssuerAndSN Method](#M_X509_HashIssuerAndSN) ### C++ (STL) Equivalent static std::string [dipki::X509::HashIssuerAndSN](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_x509.html#aab9ad8e8fa8aadf6df0c37c8a3ea89e1 "External link") (const std::string &certFile, HashAlg hashAlg=HashAlg::Sha1) ### Python Equivalent static [X509.cert_hashissuersn](https://cryptosys.net/pki/pydocpki/class-stubs/X509.html#cryptosyspki.X509.cert_hashissuersn "External link")(certfilename, hashalg=0) ### Remarks For the "raw" VBA/C function, the user must allocate an output string buffer *szOutput* of the required length. Specify a zero *nOutChars* or an empty string for *szOutput* to find the required length. ANSI C users [must add one to this value](#cusersaddone) when allocating memory. The certificate may be in binary BER format or base64 PEM format. ### Example (VBA core function) ``` Dim nRet As Long Dim strCertName As String Dim strOutput As String * PKI_MAX_HASH_CHARS strCertName = "BobRSASignByCarl.cer" ' Set dir to suit nRet = X509_HashIssuerAndSN(strCertName, strOutput, Len(strOutput), 0) Debug.Print "X509_HashIssuerAndSN returns " & nRet & " for " & strCertName & ": " & Left(strOutput, nRet) ``` Should result in ``` X509_HashIssuerAndSN returns 40 for BobRSASignByCarl.cer: 483538bca32adeb3134fe9f74d1ae74cc9ed2e9e ``` ### Example (VBA wrapper function) ``` Dim strCertString As String strCertString = x509ReadStringFromFile("AliceRSASignByCarl.cer") Debug.Print strCertString Debug.Print "CertThumb=" & x509CertThumb(strCertString) strCertString = x509ReadCertStringFromP7Chain("alice_bob_carl_certs.p7c", 3) Debug.Print strCertString Debug.Print "CertThumb=" & x509CertThumb(strCertString) Debug.Print "HashIssuerAndSN=" & x509HashIssuerAndSN(strCertString, PKI_HASH_SHA256) ``` ### See Also [X509_CertIsValidNow](#X509_CertIsValidNow) [X509_CertThumb](#X509_CertThumb) [[Contents](#topofpage)] [[Index](#index)] X509_KeyUsageFlags ------------------------------------------------- Returns a bitfield containing the keyUsage flags for an X.509 certificate. ### VBA/VB6 Syntax `Public Declare Function X509_KeyUsageFlags Lib "diCrPKI.dll" (ByVal strCertFile As String) As Long` `nRet = X509_KeyUsageFlags(strCertFile)` ### C/C++ Syntax `long __stdcall X509_KeyUsageFlags(const char *szCertFile);` ### Parameters *szCertFile* : [in] with the filename of the X.509 certificate (or [base64 representation](#base64forcert)). ### Returns (VBA/C) If successful, it returns a positive integer containing the keyUsage flags; or 0 if no keyUsage flags are set; otherwise it returns a negative [error code](#errorcodes). ### .NET Equivalent [X509.KeyUsageFlags Method](#M_X509_KeyUsageFlags) ### Python Equivalent static [X509.key_usage_flags](https://cryptosys.net/pki/pydocpki/class-stubs/X509.html#cryptosyspki.X509.key_usage_flags "External link")(certfile) ### Remarks The certificate may be in binary BER format or base64 PEM format. The presence of a key usage flag can be ascertained by AND'ing the result with the bitfield value for each flag. ``` digitalSignature 0x0001 nonRepudiation 0x0002 keyEncipherment 0x0004 dataEncipherment 0x0008 keyAgreement 0x0010 keyCertSign 0x0020 cRLSign 0x0040 encipherOnly 0x0080 decipherOnly 0x0100 ``` These values are defined as `PKI_X509_KEYUSAGE_DIGITALSIGNATURE`, etc. ### Example This shows how to find and display the key usage flags for a given certificate. ``` Dim nRet As Long Dim strCertName As String strCertName = "CarlRSASelf.cer" nRet = X509_KeyUsageFlags(strCertName) ' Show the result as a hex number Debug.Print "keyUsage flags are (0x" & Hex(nRet) & "):" ' Check all the keyUsage flags in turn If (nRet And PKI_X509_KEYUSAGE_DIGITALSIGNATURE) <> 0 Then Debug.Print "digitalSignature" If (nRet And PKI_X509_KEYUSAGE_NONREPUDIATION) <> 0 Then Debug.Print "nonRepudiation" If (nRet And PKI_X509_KEYUSAGE_KEYENCIPHERMENT) <> 0 Then Debug.Print "keyEncipherment" If (nRet And PKI_X509_KEYUSAGE_DATAENCIPHERMENT) <> 0 Then Debug.Print "dataEncipherment" If (nRet And PKI_X509_KEYUSAGE_KEYAGREEMENT) <> 0 Then Debug.Print "keyAgreement" If (nRet And PKI_X509_KEYUSAGE_KEYCERTSIGN) <> 0 Then Debug.Print "keyCertSign" If (nRet And PKI_X509_KEYUSAGE_CRLSIGN) <> 0 Then Debug.Print "cRLSign" If (nRet And PKI_X509_KEYUSAGE_ENCIPHERONLY) <> 0 Then Debug.Print "encipherOnly" If (nRet And PKI_X509_KEYUSAGE_DECIPHERONLY) <> 0 Then Debug.Print "decipherOnly" ' Alternatively, use X509_QueryCert to find these values as a string directly Debug.Print "Use X509_QueryCert..." Dim strOutput As String Dim strQuery As String Dim nChars As Long strQuery = "keyUsageString" nChars = X509_QueryCert("", 0, strCertName, strQuery, 0) If nChars < 0 Then Exit Sub ' ERROR strOutput = String(nChars, " ") nChars = X509_QueryCert(strOutput, Len(strOutput), strCertName, strQuery, 0) Debug.Print "X509_QueryCert('" & strQuery & "')=" & strOutput ``` For the S/MIME test file `CarlRSASelf.cer`, this displays ``` keyUsage flags are (0x61): digitalSignature keyCertSign cRLSign Use X509_QueryCert... X509_QueryCert('keyUsageString')=digitalSignature,keyCertSign,cRLSign ``` ### See Also [X509_QueryCert](#X509_QueryCert) [[Contents](#topofpage)] [[Index](#index)] X509_MakeCert --------------------------------------- Creates an X.509 certificate using subject's public key and issuer's private key files. ### VBA/VB6 Syntax `Public Declare Function X509_MakeCert Lib "diCrPKI.dll" (ByVal strNewCertFile As String, ByVal strIssuerCertFile As String, ByVal strSubjectPubKeyFile As String, ByVal strIssuerPriKeyFile As String, ByVal nCertNum As Long, ByVal nYearsValid As Long, ByVal strDistName As String, ByVal strExtensions As String, ByVal KeyUsageFlags As Long, ByVal strPassword As String, ByVal nOptions As Long) As Long` `nRet = X509_MakeCert(strNewCertFile, strIssuerCertFile, strSubjectPubKeyFile, strIssuerPriKeyFile, nCertNum, nYearsValid, strDistName, strExtensions, KeyUsageFlags, strPassword, nOptions)` ### C/C++ Syntax `long __stdcall X509_MakeCert(const char *szNewCertFile, const char *szIssuerCertFile, const char *szSubjectPubKeyFile, const char *szIssuerPriKeyFile, long nCertNum, long nYearsValid, const char *szDistName, const char *szExtensions, long nKeyUsageFlags, const char *szPassword, long nOptions);` ### Parameters *szNewCertFile* : [in] Name of new certificate file to be created. *szIssuerCertFile* : [in] Name of issuer's X.509 certificate file (or its [base64 representation](#base64forcert) or as a [PEM string](#pemstring)). *szSubjectPubKeyFile* : [in] Name of subject's public key file or a [PEM string](#pemstring) containing the key, or a valid internal key string. *szIssuerPriKeyFile* : [in] Name of issuer's private key file (encrypted or unencrypted) or a [PEM string](#pemstring) containing the key, or a valid internal key string. *nCertNum* : [in] Serial number for new certificate. Ignored if `serialNumber` is set in *szExtensions*. *nYearsValid* : [in] Number of years certificate is to be valid from current date and hour (can be changed with *szExtensions*). *szDistName* : [in] Distinguished name string. See [Specifying Distinguished Names](#distnames) for more details. *szExtensions* : [in] Extensions: a list of attribute-value pairs separated by semicolons (;). See [X.509 Extensions Parameter](#x509extensions). Specify `""` or `NULL` to ignore. *nKeyUsageFlags* : [in] Bit flags to set Key Usage extension: | Option | To set | | --- | --- | | `PKI_X509_KEYUSAGE_DIGITALSIGNATURE` | `digitalSignature` | | `PKI_X509_KEYUSAGE_NONREPUDIATION` | `nonRepudiation` | | `PKI_X509_KEYUSAGE_KEYENCIPHERMENT` | `keyEncipherment` | | `PKI_X509_KEYUSAGE_DATAENCIPHERMENT` | `dataEncipherment` | | `PKI_X509_KEYUSAGE_KEYAGREEMENT` | `keyAgreement` | | `PKI_X509_KEYUSAGE_KEYCERTSIGN` | `keyCertSign` | | `PKI_X509_KEYUSAGE_CRLSIGN` | `cRLSign` | | `PKI_X509_KEYUSAGE_ENCIPHERONLY` | `encipherOnly` | | `PKI_X509_KEYUSAGE_DECIPHERONLY` | `decipherOnly` | Add to combine options. Specify zero to omit Key Usage extension. *szPassword* : [in] Password for issuer's encrypted private key file. Specify the empty string `""` if key not encrypted *[New in v12.0]*. *nOptions* : [in] Option flags. Choose one signature algorithm from: `PKI_SIG_SHA1RSA` (0) to use `sha1WithRSAEncryption` (default - CAUTION) `PKI_SIG_SHA224RSA` to use `sha224WithRSAEncryption` `PKI_SIG_SHA256RSA` to use `sha256WithRSAEncryption` [minimum recommended] `PKI_SIG_SHA384RSA` to use `sha384WithRSAEncryption` `PKI_SIG_SHA512RSA` to use `sha512WithRSAEncryption` `PKI_SIG_MD5RSA` to use `md5WithRSAEncryption` [legacy, not recommended] `PKI_SIG_MD2RSA` to use `md2WithRSAEncryption` [legacy, definitely not recommended] `PKI_SIG_RSA_PSS_SHA1` to use `RSA-PSS-SHA1` `PKI_SIG_RSA_PSS_SHA224` to use `RSA-PSS-SHA224` `PKI_SIG_RSA_PSS_SHA256` to use `RSA-PSS-SHA256` `PKI_SIG_RSA_PSS_SHA384` to use `RSA-PSS-SHA384` `PKI_SIG_RSA_PSS_SHA512` to use `RSA-PSS-SHA512` `PKI_SIG_ECDSA_SHA1` to use `ecdsaWithSHA1` `PKI_SIG_ECDSA_SHA224` to use `ecdsaWithSHA224` `PKI_SIG_ECDSA_SHA256` to use `ecdsaWithSHA256` `PKI_SIG_ECDSA_SHA384` to use `ecdsaWithSHA384` `PKI_SIG_ECDSA_SHA512` to use `ecdsaWithSHA512` `PKI_SIG_ED25519` to use `Ed25519` *[New in v20.0]* `PKI_SIG_ED448` to use `Ed448` *[New in v22.0]* And add any combination of these:- `PKI_X509_VERSION1` to generate a Version 1 certificate, i.e. no extensions (default = Version 3). `PKI_X509_CA_TRUE` to set the `basicConstraints` subject type to be a CA (default = End Entity) `PKI_X509_NO_BASIC` to disable the `basicConstraints` extension (default = include) `PKI_X509_UTF8` to encode the subject's DN fields as `UTF8String` (default = PrintableString) `PKI_X509_FORMAT_PEM` to save the certificate in PEM format (default = DER-encoded binary) `PKI_X509_AUTHKEYID` to add the issuer's KeyIdentifier, if present, as an AuthorityKeyIdentifer (default = do not add) Specialist options:- `PKI_PSS_SALTLEN_ZERO` to use a zero-length salt in an RSA-PSS signature. `PKI_SIG_DETERMINISTIC` to use the deterministic digital signature generation procedure of [[RFC6979](#RFC6979)] for an ECDSA signature. ### Returns (VBA/C) If successful, the return value is zero; otherwise it returns a nonzero [error code](#errorcodes). ### .NET Equivalent [X509.MakeCert Method](#M_X509_MakeCert) ### C++ (STL) Equivalent static int [dipki::X509::MakeCert](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_x509.html#abc55dc55d87795a5eec2c6a2754d57ec "External link") (const std::string &newCertFile, const std::string &issuerCert, const std::string &subjectPubKeyFile, const std::string &issuerPriKeyFile, const std::string &password, int certNum, int yearsValid, const std::string distName, const std::string extns="", KeyUsageOptions keyUsageOptions=KeyUsageOptions::NoKeyUsageOption, SigAlg sigAlg=SigAlg::Default, CertOptions opts=CertOptions::Default_CertOpt) ### Python Equivalent static [X509.make_cert](https://cryptosys.net/pki/pydocpki/class-stubs/X509.html#cryptosyspki.X509.make_cert "External link")(newcertfile, issuercert, subject_pubkeyfile, issuer_prikeyfile, password, certnum=0, yearsvalid=0, distname="", extns="", keyusage=KeyUsageFlags.NONE, sigalg=0, opts=0) ### Remarks At least one valid attribute for the subject's distinguished name (DN) must be included. A version 1 certificate created using the `PKI_X509_VERSION1` flag will, by definition, exclude any version 3 extensions. If the `PKI_X509_UTF8` flag is set, each attribute of the subject's DN will be encoded as a `UTF8String`. Otherwise the default encoding will be `PrintableString` or, if a non-printable character is specified, then as either `IA5String` or `T61String` - see [Specifying Distinguished Names](#distnames) for more details. The encoding of the issuer's DN will be exactly as in the issuer's certficate. If the `PKI_X509_AUTHKEYID` flag is set then an `authorityKeyIdentifer` extension will be set *if* there is a corresponding `subjectKeyIdentifer` in the issuer's certificate. Otherwise no such extension will be set. The default validity period is from one minute ago by the system clock for a period of a whole number of years set by the *nYearsValid* parameter. This time will always have the seconds set to 01. A different validity period can be set using the `notBefore` and `notAfter` attributes in the *szExtensions* parameter (see [X509 Extensions Parameter](#x509extensions)). The serial number can be set to be an integer in the range 1 to 2,147,483,647 using the *nCertNum* parameter, or (once you have used these up!) it can be set to a larger value, perhaps a random large integer represented by a hexadecimal string, using the `serialNumber` attribute in the *szExtensions* parameter (see [X509 Extensions Parameter](#x509extensions)). As an alternative, you can create a new X.509 certificate using a PKCS-10 certificate signing request (CSR) file. Pass the name of the CSR file in the *szSubjectPubKeyFile* parameter and set the *szDistName* empty `""`. The empty distinguished name parameter is a flag that a CSR file is being used. See the example below. *[New in v12.0]* Added support for unencrypted private key files for *szIssuerPriKeyFile* as well as encrypted ones. Specify `szPassword=""` to flag an unencrypted key. *[New in v12.0]* Added support for RSA-PSS and ECDSA signatures. Both the signing key and the subject's public key must be either both RSA keys for the RSA options, or both EC keys for the ECDSA signature options. The MGF hash function for RSA-PSS signatures in an X.509 certificate is *always* the same as the signature hash function. The signing key must be long enough to include the specified digest value and other encoding bytes. For example, a 1024-bit RSA key is too short to sign using RSA-PSS-SHA512 (see [RSA signature and encryption schemes](#rsaschemes)). Not all signature options provided may be accepted by other applications. Note also that both these signature schemes are probabilistic and each new signature contains randomly generated salt values, so you won't reproduce the same certificate even with identical inputs. Use the specialist options `PKI_PSS_SALTLEN_ZERO` and `PKI_SIG_DETERMINISTIC` with RSA-PSS and ECDSA, respectively, to force a deterministic (fixed) result. *[New in v12.3]* Added ability to specify an empty subjectName, to set extKeyUsage extension purposes in the [X.509 Extensions Parameter](#x509extensions), and mark an [arbitrary extension](#arbitraryx509extn) as critical. Setting `szDistName = "$"` will create an X.509 document with an empty subjectName. At least one field for a subject alternative name extension (`altSubjectName`) must be specified and the extension will automatically be marked critical. ``` char *dn = "$"; char *extns = "iPAddress=192.168.15.1;extKeyUsage=serverAuth,clientAuth,emailProtection,critical;"; ``` *[New in v20.5]* Added ability to pass an internal key string for the subject's public key and signer's private key. ### Example ``` Dim nRet As Long Dim strNewCertFile As String Dim strIssuerCert As String Dim strSubjectPubKeyFile As String Dim strIssuerPriKeyFile As String Dim strPassword As String Dim nCertNum As Long Dim nYearsValid As Long Dim strDistName As String Dim strEmail As String strNewCertFile = "myuser.cer" strIssuerCert = "myca.cer" strSubjectPubKeyFile = "mykey.pub" strIssuerPriKeyFile = "myca.p8e" strPassword = "password" '!! nCertNum = &H101 nYearsValid = 4 strDistName = "CN=My User;O=Test Org;OU=Unit;C=AU;L=My Town;S=State;E=myuser@testorg.com" strEmail = "myuser@testorg.com" nRet = X509_MakeCert(strNewCertFile, strIssuerCert, strSubjectPubKeyFile, strIssuerPriKeyFile, _ nCertNum, nYearsValid, strDistName, strEmail, 0, strPassword, 0) If nRet <> 0 Then Debug.Print nRet & " " & pkiErrorLookup(nRet) Else Debug.Print "Success, created X.509 cert " & strNewCertFile End If ``` The above example will create a new X.509 certificate with filename `myuser.cer`. The certificate will be issued by "myca" with serial number 257 (0x101) for the subject with common name "My User", etc. It will be valid from one minute ago today for 4 years. The subject's public key in file `mykey.pub` will be included and it will be signed by the issuer with certificate `myca.cer` and private key in file `myca.p8e`. The next example in C uses the advanced *szExtensions* parameter to re-create exactly Alice's certificate from the S/MIME examples [[SMIME-EX](#SMIME-EX)]. ``` char *certname; char *issuercert = "CarlRSASelf.cer"; char *pubfile = "AlicePubRSA.pub"; char *epkfile = "CarlPrivRSASign.p8e"; char *password = "password"; char *certfile = "AliceRSA-dup.cer"; char *dn = "CN=AliceRSA"; char *extns = "rfc822name=AliceRSA@example.com;" "serialNumber=46346BC7800056BC11D36E2EC410B3B0;" "subjectKeyIdentifier=77D2B4D1B74C8A8AA3CE459DCEEC3CA03AE3FF50;" "notBefore=1999-09-19T01:08:47;" "notAfter=2039-12-31;" ; long keyUsage = PKI_X509_KEYUSAGE_DIGITALSIGNATURE + PKI_X509_KEYUSAGE_NONREPUDIATION; long lRet; char digest[PKI_SHA1_CHARS+1]; /* Make an end-user cert identical to RFC4134 AliceRSASignByCarl.cer */ certname = certfile; lRet = X509_MakeCert(certname, issuercert, pubfile, epkfile, 0, 99, dn, extns, keyUsage, password, PKI_X509_AUTHKEYID); assert(lRet == 0); printf("Created end-user X.509 certificate '%s'\n", certname); /* Check its SHA-1 thumbprint */ X509_CertThumb(certname, digest, sizeof(digest)-1, 0); printf("SHA-1 Thumb=%s\n", digest); ``` This should give the output ``` Created end-user X.509 certificate 'AliceRSA-dup.cer' SHA-1 Thumb=b30c48855055c2e64ce3196492d4b83831a6b3cb ``` ### See Also [X509_MakeCertSelf](#X509_MakeCertSelf) [[Contents](#topofpage)] [[Index](#index)] X509_MakeCertSelf ----------------------------------------------- Creates a self-signed X.509 certificate. ### VBA/VB6 Syntax `Public Declare Function X509_MakeCertSelf Lib "diCrPKI.dll" (ByVal strNewCertFile As String, ByVal strPriKeyFile As String, ByVal nCertNum As Long, ByVal nYearsValid As Long, ByVal strDistName As String, ByVal strExtensions As String, ByVal KeyUsageFlags As Long, ByVal strPassword As String, ByVal nOptions As Long) As Long` `nRet = X509_MakeCertSelf(strNewCertFile, strPriKeyFile, nCertNum, nYearsValid, strDistName, strExtensions, KeyUsageFlags, strPassword, nOptions)` ### C/C++ Syntax `long __stdcall X509_MakeCertSelf(const char *szNewCertFile, const char *szPriKeyFile, long nCertNum, long nYearsValid, const char *szDistName, const char *szExtensions, long nKeyUsageFlags, const char *szPassword, long nOptions);` ### Parameters *szNewCertFile* : [in] Name of new certificate file to be created. *szPriKeyFile* : [in] Name of issuer's private key file (encrypted or unencrypted) or a [PEM string](#pemstring) containing the key, or a valid internal key string. *nCertNum* : [in] Serial number for new certificate. Ignored if `serialNumber` is set in *szExtensions*. *nYearsValid* : [in] Number of years certificate is to be valid starting at current date and hour (can be changed with *szExtensions*). *szDistName* : [in] Distinguished name string (required). See [Specifying Distinguished Names](#distnames) for more details. *szExtensions* : [in] Extensions: optional list of attribute-value pairs separated by semicolons (;). See [X.509 Extensions Parameter](#x509extensions). Specify `""` or `NULL` to ignore. *nKeyUsageFlags* : [in] Flags to set Key Usage extensions: | `PKI_X509_KEYUSAGE_DIGITALSIGNATURE` | to set `digitalSignature` | | --- | --- | | `PKI_X509_KEYUSAGE_NONREPUDIATION` | to set `nonRepudiation` | | `PKI_X509_KEYUSAGE_KEYENCIPHERMENT` | to set `keyEncipherment` | | `PKI_X509_KEYUSAGE_DATAENCIPHERMENT` | to set `dataEncipherment` | | `PKI_X509_KEYUSAGE_KEYAGREEMENT` | to set `keyAgreement` | | `PKI_X509_KEYUSAGE_KEYCERTSIGN` | to set `keyCertSign` | | `PKI_X509_KEYUSAGE_CRLSIGN` | to set `cRLSign` | | `PKI_X509_KEYUSAGE_ENCIPHERONLY` | to set `encipherOnly` | | `PKI_X509_KEYUSAGE_DECIPHERONLY` | to set `decipherOnly` | Add to combine options. Specify zero to omit Key Usage extension. *szPassword* : [in] containing password for Issuer's encrypted private key file. Specify the empty string `""` if key not encrypted *[New in v12.0]*. *nOptions* : [in] Option flags. Choose one signature algorithm from: `PKI_SIG_SHA1RSA` (0) to use `sha1WithRSAEncryption` (default - CAUTION) `PKI_SIG_SHA224RSA` to use `sha224WithRSAEncryption` `PKI_SIG_SHA256RSA` to use `sha256WithRSAEncryption` [minimum recommended] `PKI_SIG_SHA384RSA` to use `sha384WithRSAEncryption` `PKI_SIG_SHA512RSA` to use `sha512WithRSAEncryption` `PKI_SIG_MD5RSA` to use `md5WithRSAEncryption` [legacy, not recommended] `PKI_SIG_MD2RSA` to use `md2WithRSAEncryption` [legacy, definitely not recommended] `PKI_SIG_RSA_PSS_SHA1` to use `RSA-PSS-SHA1` `PKI_SIG_RSA_PSS_SHA224` to use `RSA-PSS-SHA224` `PKI_SIG_RSA_PSS_SHA256` to use `RSA-PSS-SHA256` `PKI_SIG_RSA_PSS_SHA384` to use `RSA-PSS-SHA384` `PKI_SIG_RSA_PSS_SHA512` to use `RSA-PSS-SHA512` `PKI_SIG_ECDSA_SHA1` to use `ecdsaWithSHA1` `PKI_SIG_ECDSA_SHA224` to use `ecdsaWithSHA224` `PKI_SIG_ECDSA_SHA256` to use `ecdsaWithSHA256` `PKI_SIG_ECDSA_SHA384` to use `ecdsaWithSHA384` `PKI_SIG_ECDSA_SHA512` to use `ecdsaWithSHA512` `PKI_SIG_ED25519` to use `Ed25519` *[New in v20.0]* `PKI_SIG_ED448` to use `Ed448` *[New in v22.0]* And add any combination of these:- `PKI_X509_VERSION1` to generate a Version 1 certificate, i.e. no extensions (default = Version 3). `PKI_X509_CA_TRUE` to set the `basicConstraints` subject type to be a CA (default = End Entity) `PKI_X509_NO_BASIC` to disable the `basicConstraints` extension (default = include) `PKI_X509_UTF8` to encode the subject's DN fields as `UTF8String` (default = PrintableString) `PKI_X509_FORMAT_PEM` to save the certificate in PEM format (default = DER-encoded binary) Specialist options:- `PKI_PSS_SALTLEN_ZERO` to use a zero-length salt in an RSA-PSS signature. `PKI_SIG_DETERMINISTIC` to use the deterministic digital signature generation procedure of [[RFC6979](#RFC6979)] for an ECDSA signature. ### Returns (VBA/C) If successful, the return value is zero; otherwise it returns a nonzero [error code](#errorcodes). ### .NET Equivalent [X509.MakeCertSelf Method](#M_X509_MakeCertSelf) ### C++ (STL) Equivalent static int [dipki::X509::MakeCertSelf](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_x509.html#a8f3dcd821cf4e2e614f9b859ffc8e675 "External link") (const std::string &newCertFile, const std::string &priKeyFile, const std::string &password, int certNum, int yearsValid, const std::string distName, const std::string extns="", KeyUsageOptions keyUsageOptions=KeyUsageOptions::NoKeyUsageOption, SigAlg sigAlg=SigAlg::Default, CertOptions opts=CertOptions::Default_CertOpt) ### Python Equivalent static [X509.make_cert_self](https://cryptosys.net/pki/pydocpki/class-stubs/X509.html#cryptosyspki.X509.make_cert_self "External link")(newcertfile, prikeyfile, password, certnum, yearsvalid, distname, extns="", keyusage=0, sigalg=0, opts=0) ### Remarks See the remarks for [`X509_MakeCert()`](#X509_MakeCert). A self-signed certificate has the same Issuer and Subject distinguished name. Add the `PKI_X509_UTF8` flag to encode the distinguished names in UTF-8. The `BasicConstraints` subject type will always be a CA for a version 3 self-signed certificate, unless explicitly excluded with the `PKI_X509_NO_BASIC` flag. ### Example ``` Dim nRet As Long Dim nKeyUsage As Long nKeyUsage = PKI_X509_KEYUSAGE_DIGITALSIGNATURE + _ PKI_X509_KEYUSAGE_KEYCERTSIGN + PKI_X509_KEYUSAGE_CRLSIGN nRet = X509_MakeCertSelf("myca.cer", "myca.p8e", 99, 10, _ "CN=My CA;O=Test Org;OU=Certificate Services", _ "", nKeyUsage, "password", 0) If nRet <> 0 Then Debug.Print nRet & " " & pkiGetLastError() Else Debug.Print "Success" End If ``` The above example will create a new self-signed X.509 certificate with filename `myca.cer`. The serial number will be 99. It will be valid from today for 10 years. The issuer's encrypted private key is in the file `myca.p8e` and has the password "password". The new certificate will be signed using the private key using the default `sha1WithRSAEncryption` algorithm. The second example below shows how to specify a distinguished name using UTF-8-encoded CJK characters. The `PKI_X509_UTF8` flag *must* be used in this case. ``` Dim nRet As Long Dim nKeyUsage As Long Dim strDN As String ' Specify DN using chinese characters in UTF-8 ' CN=da wei (U+5927, U+536B) ' C=zhong guo (U+4E2D, U+56FD) strDN = "CN=#xE5A4A7E58DAB;C=#xe4b8ade59bbd" nKeyUsage = PKI_X509_KEYUSAGE_DIGITALSIGNATURE + PKI_X509_KEYUSAGE_KEYCERTSIGN + PKI_X509_KEYUSAGE_CRLSIGN nRet = X509_MakeCertSelf("myca-chinadavid.cer", "myca.p8e", _ &H888, 4, strDN, "", nKeyUsage, "password", PKI_X509_UTF8) If nRet <> 0 Then Debug.Print nRet & " " & pkiGetLastError() Else Debug.Print "Success" End If ``` ### See Also [X509_MakeCert](#X509_MakeCert) [[Contents](#topofpage)] [[Index](#index)] X509_MakeCRL ------------------------------------- Creates an X.509 Certificate Revocation List (CRL). ### VBA/VB6 Syntax `Public Declare Function X509_MakeCRL Lib "diCrPKI.dll" (ByVal strCrlFile As String, ByVal strIssuerCert As String, ByVal strIssuerKeyFile As String, ByVal strPassword As String, ByVal strRevokedCertList As String, ByVal strExtensions As String, ByVal nOptions As Long) As Long` `nRet = X509_MakeCRL(strCrlFile, strIssuerCert, strIssuerKeyFile, strPassword, strRevokedCertList, strExtensions, nOptions)` ### C/C++ Syntax `long __stdcall X509_MakeCRL(const char *szCrlFile, const char *szIssuerCert, const char *szIssuerKeyFile, const char *szPassword, const char *szRevokedCertList, const char *szExtensions, long nOptions);` ### Parameters *szCrlFile* : [in] with name of new CRL file to be created. *szIssuerCert* : [in] with name of issuer's X.509 certificate file (or [base64 representation](#base64forcert)). *szIssuerKeyFile* : [in] with name of issuer's encrypted private key file. *szPassword* : [in] containing password for issuer's encrypted private key file. *szRevokedCertList* : [in] with list of revoked certificates in format `serialNumber,revocationDate; ...` or the empty string `""` for no revoked certificates. See the Remarks section below for more details. *szExtensions* : [in] (optional) containing one or more attribute-value pairs separated by semicolons (`;`). Valid attribute-value pairs are: * `thisUpdate`= * `nextUpdate`= *nOptions* : [in] Option flags. Choose one signature algorithm from: `PKI_SIG_SHA1RSA` (0) to use `sha1WithRSAEncryption` (default - CAUTION) `PKI_SIG_SHA224RSA` to use `sha224WithRSAEncryption` `PKI_SIG_SHA256RSA` to use `sha256WithRSAEncryption` [minimum recommended] `PKI_SIG_SHA384RSA` to use `sha384WithRSAEncryption` `PKI_SIG_SHA512RSA` to use `sha512WithRSAEncryption` `PKI_SIG_MD5RSA` to use `md5WithRSAEncryption` [legacy, not recommended] `PKI_SIG_MD2RSA` to use `md2WithRSAEncryption` [legacy, definitely not recommended] `PKI_SIG_RSA_PSS_SHA1` to use `RSA-PSS-SHA1` `PKI_SIG_RSA_PSS_SHA224` to use `RSA-PSS-SHA224` `PKI_SIG_RSA_PSS_SHA256` to use `RSA-PSS-SHA256` `PKI_SIG_RSA_PSS_SHA384` to use `RSA-PSS-SHA384` `PKI_SIG_RSA_PSS_SHA512` to use `RSA-PSS-SHA512` `PKI_SIG_ECDSA_SHA1` to use `ecdsaWithSHA1` `PKI_SIG_ECDSA_SHA224` to use `ecdsaWithSHA224` `PKI_SIG_ECDSA_SHA256` to use `ecdsaWithSHA256` `PKI_SIG_ECDSA_SHA384` to use `ecdsaWithSHA384` `PKI_SIG_ECDSA_SHA512` to use `ecdsaWithSHA512` `PKI_SIG_ED25519` to use `Ed25519` *[New in v20.0]* `PKI_SIG_ED448` to use `Ed448` *[New in v22.0]* And add any combination of these:- `PKI_X509_FORMAT_PEM` to save the certificate in PEM format (default = DER-encoded binary) Specialist options:- `PKI_PSS_SALTLEN_ZERO` to use a zero-length salt in an RSA-PSS signature. `PKI_SIG_DETERMINISTIC` to use the deterministic digital signature generation procedure of [[RFC6979](#RFC6979)] for an ECDSA signature. ### Returns (VBA/C) If successful, the return value is zero; otherwise it returns a nonzero [error code](#errorcodes). ### .NET Equivalent [X509.MakeCRL Method](#M_X509_MakeCRL) ### C++ (STL) Equivalent static int [dipki::X509::MakeCRL](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_x509.html#a8c1e71c90536e86f8f45a1f22af57d05 "External link") (const std::string &newFile, const std::string &issuerCert, const std::string &priKeyFile, const std::string &password, const std::string revokedCertList, const std::string extns="", SigAlg sigAlg=SigAlg::Default, CrlOptions opts=CrlOptions::Default_CrlOpt) ### Python Equivalent static [X509.make_crl](https://cryptosys.net/pki/pydocpki/class-stubs/X509.html#cryptosyspki.X509.make_crl "External link")(newcrlfile, issuercert, prikeyfile, password, revokedcertlist="", extns="", sigalg=0, opts=0) ### Remarks This function creates a version 1 CRL file with no extensions or cRLReason's. The parameter *szRevokedCertList* must be in the form ``` serialNumber,revocationDate;serialNumber,revocationDate; ... ``` The serialNumber must either be a positive decimal number (e.g. `123`) or the number in hex format preceded by `"#x"` (e.g. `"#x0102deadbeef"`). The revocation date must be in [ISO date format](#iso8601datetime) (e.g. `2009-12-31` or `2009-12-31T12:59:59Z`). By default, the `lastUpdate` time in the CRL is set to the time given by the system clock, and `nextUpdate` time is left empty. You can specify your own times using the `lastUpdate` and `nextUpdate` attributes in the *szExtensions* parameter. Times, if specified, must be in [ISO 8601 format](#iso8601datetime) and are always interpreted as GMT times whether or not you add a "Z". ### Example ``` Dim nRet As Long Dim strCrlFile As String Dim strIssuerFile As String Dim strKeyFile As String Dim strPassword As String Dim strCertList As String Dim strExtension As String ' Create a new CRL dated with the current system time strCrlFile = "CarlsNew.crl" strIssuerFile = "CarlRSASelf.cer" strKeyFile = "CarlPrivRSASign.p8e" ' CAUTION: DO NOT HARD-CODE REAL PASSWORDS! strPassword = "password" strCertList = "1,2007-12-31; 2, 2009-12-31T12:59:59Z; 66000,2066-01-01; #x0102deadbeef,2010-02-28T01:01:59" nRet = X509_MakeCRL(strCrlFile, strIssuerFile, strKeyFile, strPassword, strCertList, "", 0) Debug.Print "X509_MakeCRL returns " & nRet & " (expected 0)" If (nRet = 0) Then Debug.Print "SUCCESS: New CRL file '" & strCrlFile & "' created." Else Debug.Print "ERROR: " & pkiErrorLookup(nRet) & ": " & pkiGetLastError() End If ' Create another CRL using specified times (NB these are GMT times, not local) strExtension = "thisUpdate=2010-04-01T12:00;nextUpdate=2010-05-01" strCrlFile = "Carl_20100401.crl" nRet = X509_MakeCRL(strCrlFile, strIssuerFile, strKeyFile, strPassword, strCertList, strExtension, 0) Debug.Print "X509_MakeCRL returns " & nRet & " (expected 0)" If (nRet = 0) Then Debug.Print "SUCCESS: New CRL file '" & strCrlFile & "' created." Else Debug.Print "ERROR: " & pkiErrorLookup(nRet) & ": " & pkiGetLastError() End If ``` The latter instruction should produce a CRL of the following form: ``` >certmgr -crl -v Carl_20100401.crl ==============CRL # 1 ========== Issuer:: [0,0] 2.5.4.3 (CN) ValueType: 4 43 61 72 6C 52 53 41 'CarlRSA' ThisUpdate:: Thu Apr 01 20:00:00 2010 NextUpdate:: Sat May 01 08:00:00 2010 SHA1 Thumbprint:: BAE05E5B E4F5E7A7 82F487CC 60F7BC31 0A643538 MD5 Thumbprint:: 20E8251E 7959BE61 41441901 60DB7FBA Version:: 0 SignatureAlgorithm:: 1.2.840.113549.1.1.5 SignatureAlgorithm.Parameters:: 05 00 '..' ----- Entries ----- [0] SerialNumber:: 01 [0] RevocationDate:: Mon Dec 31 08:00:00 2007 [0] Extensions:: NONE [1] SerialNumber:: 02 [1] RevocationDate:: Thu Dec 31 20:59:59 2009 [1] Extensions:: NONE [2] SerialNumber:: 01 01 D0 [2] RevocationDate:: Fri Jan 01 08:00:00 2066 [2] Extensions:: NONE [3] SerialNumber:: 01 02 DE AD BE EF [3] RevocationDate:: Sun Feb 28 09:01:59 2010 [3] Extensions:: NONE ============================================== CertMgr Succeeded ``` Note that the times given by CERTMGR are local, not GMT, and the output above is from a computer in a timezone 8 hours ahead of GMT. Different times will be shown in different timezones. ### See Also [X509_CheckCertInCRL](#X509_CheckCertInCRL) [[Contents](#topofpage)] [[Index](#index)] X509_QueryCert ----------------------------------------- Queries an X.509 certificate file for selected information. ### VBA/VB6 Syntax `Public Declare Function X509_QueryCert Lib "diCrPKI.dll" (ByVal strDataOut As String, ByVal nOutChars As Long, ByVal strFileIn As String, ByVal strQuery As String, ByVal nOptions As Long) As Long` `nRet = X509_QueryCert(strDataOut, nOutChars, strFileIn, strQuery, nOptions) As Long` ### C/C++ Syntax `long __stdcall X509_QueryCert(char *szOutput, long nOutChars, const char *szCertFile, const char *szQuery, long nOptions);` ### Parameters *szOutput* : [out] to receive the output. *nOutChars* : [in] specifying the length of the output string. *szCertFile* : [in] with name of X.509 certificate file (or [base64 representation](#base64forcert)). *szQuery* : [in] specifying the query (see Remarks below). *nOptions* : [in] option flags: `PKI_DEFAULT` (0) for default options `PKI_QUERY_GETTYPE` to return the type of data returned for a given query. `PKI_X509_LATIN1` to try and convert Unicode/UTF-8/T.61 attribute strings to Latin-1 (ISO-8859-1) `PKI_X509_UTF8` to output attribute strings encoded in UTF-8 *[New in v20.3]* `PKI_X509_LDAP` to output the distinguished name in [LDAP string representation](#ldapstring) (for queries "issuerName" and "subjectName" only) `PKI_X509_DECIMAL` to output the serial number in decimal format instead of hex (for query "serialNumber" only) ### Returns (VBA/C) If successful, the return value is a positive integer giving either the result itself (if the result is a number) or the number of characters in the output string (if the query is looking for a string). If the item queried is not present, the return value is zero. If there is an error (e.g. a missing or invalid certificate file), it returns a negative [error code](#errorcodes). ### VBA Wrapper Syntax Public Function [`x509QueryCert`](#VB_x509QueryCert) (szCertFile As String, szQuery As String, Optional nOptions As Long = 0) As String ### .NET Equivalent [X509.QueryCert Method](#M_X509_QueryCert) ### C++ (STL) Equivalent static std::string [dipki::X509::QueryCert](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_x509.html#ac7b07eccfbb6ed11d98abd9808119633 "External link") (const std::string &certFile, const std::string &query, OutputOpts outOpts=OutputOpts::Default_OutputOpt) ### Python Equivalent static [X509.query_cert](https://cryptosys.net/pki/pydocpki/class-stubs/X509.html#cryptosyspki.X509.query_cert "External link")(filename, query, opts=0) ### Remarks Valid queries are (case-insenitive): | Query String | Returns | Data Type | | --- | --- | --- | | `version` | X.509 version number, e.g. 1 or 3. | Number | | `serialNumber` | Serial number in hex-encoded format | String | | `signatureAlgorithm` | Signature algorithm used, e.g. `"sha1WithRSAEncryption"`. | String | | `sigAlgId` | ID of signature algorithm used, see `PKI_SIG_*` values | Number | | `signatureValue` | Signature value in hex-encoded format | String | | `notBefore` | Date on which the certificate validity period begins in format `yyyy-mm-ddThh:nn:ssZ` | String | | `notAfter` | Date on which the certificate validity period ends in format `yyyy-mm-ddThh:nn:ssZ` | String | | `issuerName` | Distinguished name (DN) of entity who has signed and issued the certificate | String | | `subjectName` | Distinguished name (DN) of the subject | String | | `subjectPublicKeyAlgorithm` | Algorithm used in subject's public key, e.g. `"dsa"` or `"rsaEncryption"`. | String | | `subjectKeyIdentifier` | The subject key identifier extension, if present, in hex-encoded format | String | | `authorityKeyIdentifier` | The authority key identifier extension, if present, in hex-encoded format | String | | `rfc822Name` | First internet mail address found contained in a subjectAltName extension, if present | String | | `isCA` | Returns 1 if the subject type is a CA, otherwise returns 0. | Number | | `keyUsageString` | `keyUsage` flags in text format, e.g. `"digitalSignature,nonRepudiation"` | String | | `extKeyUsageString` | `extKeyUsage` purposes in text format, e.g. `"codeSigning,timeStamping"` | String | | `cRLDistributionPointsURI` | First URI found in `cRLDistributionPoints`, if any | String | | `authorityInfoAccessURI` | First URI found in `authorityInfoAccess`, if any | String | | `subjectAltName` | Subject alternative name extension, if present. *[New in v10.0]* | String | | `hashAlgorithm` | Hash algorithm used in signature, e.g. `"sha256"`. *[New in v12.0]* | String | | `pssParams` | Parameters used for RSA-PSS (if applicable). *[New in v12.0]* | String | Some of these queries duplicate or complement existing functions: * `"notBefore"` = [`X509_CertIssuedOn()`](#X509_CertIssuedOn) * `"notAfter"` = [`X509_CertExpiresOn()`](#X509_CertExpiresOn) * `"serialNumber"` = [`X509_CertSerialNumber()`](#X509_CertSerialNumber) * `"subjectName"` = [`X509_CertSubjectName()`](#X509_CertSubjectName) * `"issuerName"` = [`X509_CertIssuerName()`](#X509_CertIssuerName) The "raw" VBA/C function behaves differently depending on whether the output is a string or a number. If the result data type is a number then it returns the value directly. If the result is a string, then it sets *szOutput* and returns the number of characters in the string. The required number of characters can be found by passing zero for *nOutChars* or a null string for *szOutput*. ANSI C users [must add one to this value](#cusersaddone) when allocating memory. Note that the VBA wrapper function and the C#/`VB.NET` methods *always* return a string, which is different from the behaviour of the raw VB6/C function. To find out the type of data returned for a given query, use the `PKI_QUERY_GETTYPE` option. The function will return either `PKI_QUERY_NUMBER` (1) or `PKI_QUERY_STRING` (2), or a negative "invalid query" error. For example ``` nRet = X509_QueryCert("", 0, "", "version", PKI_QUERY_GETTYPE); ``` will return `PKI_QUERY_NUMBER`. If an attribute value is encoded in a multi-byte-character string format (such as UTF8String or BMPString), the value will be expressed as a hexadecimal-encoded string *[NB changed in v3.9]* preceded by the hash symbol (`'#'` U+0023), e.g. ``` "C=TW;O=E8 A1 8C E6 94 BF E9 99 A2" (v3.8 and earlier) "C=TW;O=#E8A18CE694BFE999A2" (v3.9 and later) ``` Use the `PKI_X509_LATIN1` option to return the string encoded in Latin-1, if possible, to help with display issues. The output from the queries `"issuerName"` and `"subjectName"` using the `PKI_X509_LDAP` option are suitable as content for the `` and `` nodes, respectively, in the `` node of an XML-DSIG document. ### Example (VBA core function) This example queries information from a sample X.509 certificate file. ``` Dim nRet As Long Dim strOutput As String Dim strQuery As String Dim strCertFile As String strCertFile = "CarlRSASelf.cer" ' Make a large buffer to receive output strOutput = String(512, " ") strQuery = "version" nRet = X509_QueryCert(strOutput, Len(strOutput), strCertFile, strQuery, 0) Debug.Print strQuery & "=" & nRet strQuery = "serialNumber" nRet = X509_QueryCert(strOutput, Len(strOutput), strCertFile, strQuery, 0) If nRet <= 0 Then Exit Sub ' catch error Debug.Print strQuery & "=" & Left(strOutput, nRet) strQuery = "signatureAlgorithm" nRet = X509_QueryCert(strOutput, Len(strOutput), strCertFile, strQuery, 0) If nRet <= 0 Then Exit Sub ' catch error Debug.Print strQuery & "=" & Left(strOutput, nRet) strQuery = "notAfter" nRet = X509_QueryCert(strOutput, Len(strOutput), strCertFile, strQuery, 0) If nRet <= 0 Then Exit Sub ' catch error Debug.Print strQuery & "=" & Left(strOutput, nRet) ``` For the S/MIME test file `CarlRSASelf.cer`, the output is as follows ``` version=3 serialNumber=46346bc7800056bc11d36e2e9ff25020 signatureAlgorithm=sha1WithRSAEncryption notAfter=2039-12-31T23:59:59Z ``` To query the type of data returned for a given query. ``` Dim nRet As Long Dim strQuery As String ' Find out the data type for a given query strQuery = "version" nRet = X509_QueryCert("", 0, "", strQuery, PKI_QUERY_GETTYPE) Debug.Print "Type(" & strQuery & ")=" & nRet strQuery = "serialNumber" nRet = X509_QueryCert("", 0, "", strQuery, PKI_QUERY_GETTYPE) Debug.Print "Type(" & strQuery & ")=" & nRet strQuery = "NotAValidQuery" nRet = X509_QueryCert("", 0, "", strQuery, PKI_QUERY_GETTYPE) Debug.Print "Type(" & strQuery & ")=" & nRet ``` This should produce output ``` Type(version)=1 Type(serialNumber)=2 Type(NotAValidQuery)=-29 ``` where 1 (`PKI_QUERY_NUMBER`) indicates a number, 2 (`PKI_QUERY_STRING`) indicates a string, and -29 (`BAD_QUERY_ERROR`) indicates an invalid query. ### Example (VBA wrapper function) ``` Debug.Print x509TextDumpToString("AliceRSASignByCarl.cer") Debug.Print x509QueryCert("AliceRSASignByCarl.cer", "subjectName") Debug.Print asn1TextDumpToString("AliceRSASignByCarl.cer") ``` ### See Also [X509_KeyUsageFlags](#X509_KeyUsageFlags) [X509_CertSubjectName](#X509_CertSubjectName) [[Contents](#topofpage)] [[Index](#index)] X509_ReadCertStringFromP7Chain ------------------------------------------------------------------------- Reads an X.509 certificate into a base64 string from PKCS-7 "certs-only" data. ### VBA/VB6 Syntax `Public Declare Function X509_ReadCertStringFromP7Chain Lib "diCrPKI.dll" (ByVal strOutput As String, ByVal nOutChars As Long, ByVal strP7cFile As String, ByVal nIndex As Long, ByVal nOptions As Long) As Long` `nRet = X509_ReadCertStringFromP7Chain(strOutput, nOutChars, strP7cFile, nIndex, nOptions) As Long` ### C/C++ Syntax `long __stdcall X509_ReadCertStringFromP7Chain(char *szOutput, long nOutChars, const char *szP7cFile, long nIndex, long nOptions);` ### Parameters *szOutput* : [out] string buffer to receive the output. *nOutChars* : [in] size of the output buffer in bytes. *szP7cFile* : [in] filename of a PKCS-7 "certs-only" file, or a string containing its [PEM textual representation](#pemstring). *nIndex* : [in] specifying which certificate (1,2,...) in the chain to extract, or (deprecated) 0 to return the count of certificates in the set. *nOptions* : [in] option flags: not used in this release. Specify zero. ### Returns (VBA/C) If successful and *nIndex* is greater than zero, the return value is a positive number indicating the number of characters in or required for the output string, which may be zero if no certificate could be found at the given index. However, if *nIndex* is zero, it returns the *count* of certificates found in the list. If an error occurred, it returns a negative [error code](#errorcodes). ### VBA Wrapper Syntax Public Function [`x509ReadCertStringFromP7Chain`](#VB_x509ReadCertStringFromP7Chain) (szP7cFile As String, nIndex As Long, Optional nOptions As Long = 0) As String ### .NET Equivalent [X509.ReadCertStringFromP7Chain Method](#M_X509_ReadCertStringFromP7Chain) ### C++ (STL) Equivalent static std::string [dipki::X509::ReadCertStringFromP7Chain](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_x509.html#a340373ecfdf7a3d6560ef7f3829ad913 "External link") (const std::string &inputFile, int index) ### Python Equivalent static [X509.read_cert_string_from_p7chain](https://cryptosys.net/pki/pydocpki/class-stubs/X509.html#cryptosyspki.X509.read_cert_string_from_p7chain "External link")(inputfile, index) ### Remarks For the "raw" VBA/C function, the user must allocate an output string buffer *szOutput* of the required length. Specify a zero *nOutChars* or an empty string for *szOutput* to find the required length. ANSI C users [must add one to this value](#cusersaddone) when allocating memory. The output is a [base64 string representation](#base64forcert) of the extracted X.509 certificate. If *nIndex* is specified as a number greater than zero, the *nIndex*'th certificate found in the list, if any, will be extracted to a base64-encoded string which can be used to represent the X.509 certificate directly in this Toolkit. This function will also extract certificates from CMS signed data objects, too. *[New in v12.2]* To find the number of certificates in the chain, use [X509_GetCertCountInP7Chain](#X509_GetCertCountInP7Chain). The old (deprecated) way to find the count of certificates was to set *nIndex* to zero. ### Example (VBA core function) The following example shows how to extract all the certificates from a PKCS-7 CertList file represented as a [PEM string](#pemstring). All transactions are carried out in memory. ``` Dim strP7 As String Dim nCerts As Long Dim nChars As Long Dim nIndex As Long Dim strCert As String Dim strDigest As String * PKI_SHA1_CHARS Dim strQuery As String * 128 ' Input is a P7 chain file in PEM format ' bob.p7b (contains 2 X.509 certs: BobRSA and CarlRSA) strP7 = "-----BEGIN PKCS7-----" & _ "MIIERQYJKoZIhvcNAQcCoIIENjCCBDICAQExADALBgkqhkiG9w0BBwGgggQaMIICJzCCAZCgAwIB" & _ "AgIQRjRrx4AAVrwR024uzV1x0DANBgkqhkiG9w0BAQUFADASMRAwDgYDVQQDEwdDYXJsUlNBMB4X" & _ "DTk5MDkxOTAxMDkwMloXDTM5MTIzMTIzNTk1OVowETEPMA0GA1UEAxMGQm9iUlNBMIGfMA0GCSqG" & _ "SIb3DQEBAQUAA4GNADCBiQKBgQCp4WeYPznVX/Kgk0FepnmJhcg1XZqRW/sdAdoZcCYXD72lItA1" & _ "hW16mGYUQVzPt7cIOwnJkbgZaTdt+WUee9mpMySjfzu7r0YBhjY0MssHA1lS/IWLMQS4zBgIFEjm" & _ "Txz7XWDE4FwfU9N/U9hpAfEF+Hpw0b6Dxl84zxwsqmqn6wIDAQABo38wfTAMBgNVHRMBAf8EAjAA" & _ "MA4GA1UdDwEB/wQEAwIFIDAfBgNVHSMEGDAWgBTp4JAnrHggeprTTPJCN04irp44uzAdBgNVHQ4E" & _ "FgQU6PS4Z9izlqQq8xGqKdOVWoYWtCQwHQYDVR0RBBYwFIESQm9iUlNBQGV4YW1wbGUuY29tMA0G" & _ "CSqGSIb3DQEBBQUAA4GBAHuOZsXxED8QIEyIcat7QGshM/pKld6dDltrlCEFwPLhfirNnJOIh/uL" & _ "t359QWHh5NZt+eIEVWFFvGQnRMChvVl52R1kPCHWRbBdaDOS6qzxV+WBfZjmNZGjOd539OgcOync" & _ "f1EHl/M28FAK3Zvetl44ESv7V+qJba3JiNiPzyvTMIIB6zCCAVSgAwIBAgIQRjRrx4AAVrwR024u" & _ "n/JQIDANBgkqhkiG9w0BAQUFADASMRAwDgYDVQQDEwdDYXJsUlNBMB4XDTk5MDgxODA3MDAwMFoX" & _ "DTM5MTIzMTIzNTk1OVowEjEQMA4GA1UEAxMHQ2FybFJTQTCBnzANBgkqhkiG9w0BAQEFAAOBjQAw" & _ "gYkCgYEA5Ev/GLgkV/R3/25ze5NxXLwzGpKSciPYQUbQzRE6BLOOr4KdvVEeF3rydiwrhjmnvdeN" & _ "GlPs5ADV6OyiNrHt4lDiMgmKP5+ZJY+4Tqu5fdWWZdoWoMW+Dq5EW+9e9Kcpy4LdrETpqpOUKQ74" & _ "GNbIV17ydsTyEWA4uRs8HZfJavECAwEAAaNCMEAwDwYDVR0TAQH/BAUwAwEB/zAOBgNVHQ8BAf8E" & _ "BAMCAYYwHQYDVR0OBBYEFOngkCeseCB6mtNM8kI3TiKunji7MA0GCSqGSIb3DQEBBQUAA4GBALee" & _ "1ATT7Snk/4mJFS5M2wzwSA8yYe7EBOwSXS3/D2RZfgrD7Rj941ZAN6cHtfA4EmFQ7e/dP+MLuGGl" & _ "pJs85p6cVJq2ldbabDu1LUU1nUkBdvq5uTH5+WsSU6D1FGCbfco+8lNrsDdvreZ019v6WuoUQWNd" & _ "zb7IDsHaao1TNBgCMQA=" & _ "-----END PKCS7-----" ' Get count of certs in P7 chain - new function in [v12.2] nIndex = 0 nCerts = X509_GetCertCountInP7Chain(strP7, 0) Debug.Print "nCerts=" & nCerts ' Read all certs For nIndex = 1 To nCerts ' Find required length of buffer nChars = X509_ReadCertStringFromP7Chain(ByVal 0&, 0, strP7, nIndex, 0) Debug.Print "X509_ReadCertStringFromP7Chain(" & nIndex & ") returns " & nChars ' Allocate memory/pre-dimension strCert = String(nChars, " ") nChars = X509_ReadCertStringFromP7Chain(strCert, Len(strCert), strP7, nIndex, 0) ' Cert is in a base64 string Debug.Print Left(strCert, 150) & "..." ' Query the cert for subject name nChars = X509_QueryCert(strQuery, Len(strQuery), strCert, "subjectName", 0) Debug.Print "subjectName='" & Left(strQuery, nChars) & "'" ' Compute the SHA-1 thumbprint of the cert nChars = X509_CertThumb(strCert, strDigest, Len(strDigest), 0) Debug.Print "SHA-1(cert)=" & Left(strDigest, nChars) Next ``` This should result in output as follows: ``` nCerts=2 X509_ReadCertStringFromP7Chain(1) returns 740 MIICJzCCAZCgAwIBAgIQRjRrx4AAVrwR024uzV1x0DANBgkqhkiG9w0BAQUFADASMRAwDgYDVQQDEwdDYXJsUlNBMB4XDTk5MDkxOTAxMDkwMloXDTM5MTIzMTIzNTk1OVowETEPMA0GA1UEAxMGQm... subjectName='CN=BobRSA' SHA-1(cert)=63f046d2dd7042e51fdc26a511ef7c81ea622d8b X509_ReadCertStringFromP7Chain(2) returns 660 MIIB6zCCAVSgAwIBAgIQRjRrx4AAVrwR024un/JQIDANBgkqhkiG9w0BAQUFADASMRAwDgYDVQQDEwdDYXJsUlNBMB4XDTk5MDgxODA3MDAwMFoXDTM5MTIzMTIzNTk1OVowEjEQMA4GA1UEAxMHQ2... subjectName='CN=CarlRSA' SHA-1(cert)=4110908f77c64c0edfc2de6273bfa9a98a9c5ce5 ``` ### Example (VBA wrapper function) ``` Dim strCertString As String strCertString = x509ReadStringFromFile("AliceRSASignByCarl.cer") Debug.Print strCertString Debug.Print "CertThumb=" & x509CertThumb(strCertString) strCertString = x509ReadCertStringFromP7Chain("alice_bob_carl_certs.p7c", 3) Debug.Print strCertString Debug.Print "CertThumb=" & x509CertThumb(strCertString) Debug.Print "HashIssuerAndSN=" & x509HashIssuerAndSN(strCertString, PKI_HASH_SHA256) 'Invalid index strCertString = x509ReadCertStringFromP7Chain("alice_bob_carl_certs.p7c", 0) Debug.Print "[" & strCertString & "]" Dim strP7File As String Dim nIndex As Long Dim nCerts As Long strP7File = "alice_bob_carl_certs.p7c" ' Call core fn with zero index to find count nCerts = X509_ReadCertStringFromP7Chain("", 0, strP7File, 0, 0) Debug.Print "nCerts=" & nCerts For nIndex = 1 To nCerts strCertString = x509ReadCertStringFromP7Chain(strP7File, nIndex) Debug.Print "subjectName: " & x509QueryCert(strCertString, "subjectName") Next ``` ### See Also [X509_GetCertFromP7Chain](#X509_GetCertFromP7Chain) [X509_GetCertCountInP7Chain](#X509_GetCertCountInP7Chain) [CMS_QuerySigData](#CMS_QuerySigData) [[Contents](#topofpage)] [[Index](#index)] X509_ReadCertStringFromPFX ----------------------------------------------------------------- Reads an X.509 certificate into a base64 string from PKCS-12 PFX/.p12 data. ### VBA/VB6 Syntax `Public Declare Function X509_ReadCertStringFromPFX Lib "diCrPKI.dll" (ByVal strOutput As String, ByVal nOutChars As Long, ByVal strPfxFile As String, ByVal strPassword As String, ByVal nOptions As Long) As Long` `nRet = X509_ReadCertStringFromPFX(strOutput, nOutChars, strPfxFile, strPassword, nOptions) As Long` ### C/C++ Syntax `long __stdcall X509_ReadCertStringFromPFX(char *szOutput, long nOutChars, const char *szPfxFile, const char *szPassword, long nOptions);` ### Parameters *szOutput* : [out] string buffer to receive the output. *nOutChars* : [in] size of the output buffer in bytes. *szPfxFile* : [in] filename of a PFX file, or a string containing its [PEM textual representation](#pemstring). *szPassword* : [in] containing password or `""` if certificate is not encrypted *nOptions* : [in] option flags: not used in this release. Specify zero. ### Returns (VBA/C) If successful, the return value is a positive number indicating the number of characters in or required for the output string; otherwise it returns a negative [error code](#errorcodes). ### VBA Wrapper Syntax Public Function [`x509ReadCertStringFromPFX`](#VB_x509ReadCertStringFromPFX) (szPfxFile As String, szPassword As String, Optional nOptions As Long = 0) As String ### .NET Equivalent [X509.ReadCertStringFromPFX Method](#M_X509_ReadCertStringFromPFX) ### C++ (STL) Equivalent static std::string [dipki::X509::ReadCertStringFromPFX](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_x509.html#a737485c8b333f51e80f7eab8ca4dc978 "External link") (const std::string &inputFile, const std::string &password) ### Python Equivalent static [X509.read_cert_string_from_pfx](https://cryptosys.net/pki/pydocpki/class-stubs/X509.html#cryptosyspki.X509.read_cert_string_from_pfx "External link")(inputfile, password) ### Remarks For the "raw" VBA/C function, the user must allocate an output string buffer *szOutput* of the required length. Specify a zero *nOutChars* or an empty string for *szOutput* to find the required length. ANSI C users [must add one to this value](#cusersaddone) when allocating memory. The default behaviour is to extract one certificate from the PFX file and output as a [base64 string representation](#base64forcert) of the extracted X.509 certificate. It will attempt to find a matching certificate for any private key, otherwise it will save the first `pkcs-12-certBag` found in the PFX file containing a `x509Certificate`. Both unencrypted certificates and certificates encrypted with the weak 40-bit encryption used by "default" in Microsoft and OpenSSL PKCS-12 files are supported, but not any other encryption algorithm. If no certificate can be found the function will return a negative `NO_DATA_ERROR` error code. ### Example (VBA core function) ``` Dim strPfx As String Dim nChars As Long Dim strCert As String Dim strDigest As String * PKI_SHA1_CHARS Dim strQuery As String * 128 Dim strPassword As String ' Input is a PFX file in PEM format ' bob.pfx (password="password") strPfx = "-----BEGIN PKCS12-----" & _ "MIIGhAIBAzCCBkoGCSqGSIb3DQEHAaCCBjsEggY3MIIGMzCCAv8GCSqGSIb3DQEHBqCCAvAwggLsAgEAMIIC5QYJKoZIhvcNAQcBMBwGCiqGSIb3DQEMAQYwDgQIawU" & _ "AVTFvAiECAggAgIICuNwEuFcRnZamZyMyIn+vH+wC5BVUtZAWNrlIqToezF7cYqt/18+HXB/46nllz+qUD3Dv9rS78MnPeAM47afFRTricHsiOpE+2eXf32lxduoF5+" & _ "CLS3S7TAhRUMp2Fh18LlukzK9lY67BGfU9Y3yCukTmwVXqe49dkj8y9JjVJhXnoc2c7eOk3o5RjXHFsAMHwirqdsESHstrDZYLMVGw5HnAamY7zQd8WUpIweAFaEDLJ" & _ "fyzqY1/LTL/txvZ9VQ/B/36HKyEpoIvuH6iOCBkebpJwWSkkffuVFbUfMLguMztL/sf+jE2NiuljSBJ9pTNsZziZWERb6CxZH0a2xkkBTciXM5Dl5efWL0GmBg+aJSI" & _ "yh+Gw5W8Q7gmnH6H9myszvW9uYv/epwCbIpHd0dRHPbL3fR4KGhFexq24tAG86tDqPKb6H6n0lSA+Oq46SwZ00xIFpVcFaO/8yVqf6+JRDGoZ55aAZF6OCi7R1GvI+6" & _ "pzz37pvP7SWfqVSuXCTNQq9uKw97SH5YftQ9hkELQ4vHCjFh4UJSBUCZgDtqR1uB/+44H5UpP8KvbETaOFJszMxsqXBMqc1uEODSNg+EHEx+yg7Bx1CcNrm+6rtThC4" & _ "9+ow18HDMxbn3lAw1ooblANvSzR4YTt68N/4dtwROOdXjwKzyg03qWK2sJaiH5LzbB5MMmrdAChb9dLoRKBN2LREob7KRKEs6v51IW1yq4UCwSmpP+RbchZwIoKVXx/" & _ "MYKjVqzGfZAgBRpXEq/KH/8R+ttFPKdab2GAEjd7hIOmetp5einQmK4C7JYE6Uyabf1IImtVhBw2dGU3GiM2zSIGqCx3bmYETZheMTAV9MMVUYe8gQeEpbXM4GAnwX0" & _ "wpS0aYapzGeA/62X2nFh21eRHVzUcf0miXVvyOy6a1vj6O6N5F1jVaCV3jCCAywGCSqGSIb3DQEHAaCCAx0EggMZMIIDFTCCAxEGCyqGSIb3DQEMCgECoIICpjCCAqI" & _ "wHAYKKoZIhvcNAQwBAzAOBAjw/dx4SlLcWwICCAAEggKALm91I8gYuPpRTCSn5pN4OQBLbI6jSW+9FGeNYvOy/+Pt3Oq0i15ZXZZez7dP8rdb0tmTCSZwVPIwtJRKxY" & _ "UNaTppUTWZhXhnmeTMtSZpFuKmo6UhW8lGUcg45sO5UKUtdH0/UgewaSUfV4L06vp4j7Fugwbp666seJJ/9vQwMAxoqj0blxNNmASAcW7yj/lA2/p4KuGlnGkv4MSW5" & _ "ViH7T24VeFXTzyFFR7UR1Nw9Blr5jdr7b2rZSdTj0GeHZ/L3FksFWJocl8PEEL4ZdVscbvO+l7vtbeBz0y9TDr/HUwt2tfqXgjckVVoJhmsczJXrG5Ai+brKnGQ7R5u" & _ "IpIsqd9O6EpG68VMMGA5iSKsLYtibieqom8mRO00sFiQharxONEdveY+3O98nG6xzHlaBdNbxVo38Y+4LK6Gc81dUWYwss3ajdiJWe0+TYQjMPF72eWctcQAoTxITpd" & _ "/j6rD7EmvLVyPIR46L4w6Gb/uz5G1T1UiLoh9luM1nRKKICyo2XllZDNO0msaub7DH1xzJzEy2OT9cwChqYfKKeWEE2BWL699fmq5RMCbIQVtE2bJDP8obu9j6HLskC" & _ "iZcJm6nC7IKS1pQ2BA/JJVKxC8ADuLOAOdicWquDd8MWL5a9HpXd5TtUlfiRecTw8IRozTLaoDVlhaYNGPzwkjL9zZ+Up5Uy6HHXMDb0aD0fgvMqdAspB1+Xlt2RgP6" & _ "CnEH2hwQqGFoA8TtijeS+DtdMy8BxJ7g1fiEH0+4UISl1vymjPI1MJCI1VlFLvpjZvKHluwjgp1SHk3tFRJLJ8a/eApvmscKXSlxcYz+5Bv8dxPGdhO/KOLQS7XZ4a8" & _ "VSg977WS1jFYMCMGCSqGSIb3DQEJFTEWBBRj8EbS3XBC5R/cJqUR73yB6mItizAxBgkqhkiG9w0BCRQxJB4iAEIAbwBiACcAcwAgAGYAcgBpAGUAbgBkAGwAeQAgAEk" & _ "ARDAxMCEwCQYFKw4DAhoFAAQUaHSMUJ415FfKGv3cZpwloKDmqgYECAreM3EkHVjCAgIIAA==" & _ "-----END PKCS12-----" ' Read in cert as string from PFX/P12 data ' Find required length of buffer nChars = X509_ReadCertStringFromPFX(ByVal 0&, 0, strPfx, "password", 0) Debug.Print "X509_ReadCertStringFromPFX() returns " & nChars ' Allocate memory/pre-dimension strCert = String(nChars, " ") nChars = X509_ReadCertStringFromPFX(strCert, Len(strCert), strPfx, "password", 0) ' Cert is in a base64 string Debug.Print Left(strCert, 150) & "..." ' Query the cert for subject name nChars = X509_QueryCert(strQuery, Len(strQuery), strCert, "subjectName", 0) Debug.Print "subjectName='" & Left(strQuery, nChars) & "'" ' Compute the SHA-1 thumbprint of the cert nChars = X509_CertThumb(strCert, strDigest, Len(strDigest), 0) Debug.Print "SHA-1(cert)=" & Left(strDigest, nChars) ``` This should result in output as follows: ``` X509_ReadCertStringFromPFX() returns 740 MIICJzCCAZCgAwIBAgIQRjRrx4AAVrwR024uzV1x0DANBgkqhkiG9w0BAQUFADASMRAwDgYDVQQDEwdDYXJsUlNBMB4XDTk5MDkxOTAxMDkwMloXDTM5MTIzMTIzNTk1OVowETEPMA0GA1UEAxMGQm... subjectName='CN=BobRSA' SHA-1(cert)=63f046d2dd7042e51fdc26a511ef7c81ea622d8b ``` ### Example (VBA wrapper function) ``` Dim strCertString As String strCertString = x509ReadCertStringFromPFX("alice.p12", "password") Debug.Print strCertString Debug.Print "CertThumb=" & x509CertThumb(strCertString) Debug.Print "HashIssuerAndSN=" & x509HashIssuerAndSN(strCertString) ``` ### See Also [X509_GetCertFromPFX](#X509_GetCertFromPFX) [[Contents](#topofpage)] [[Index](#index)] X509_ReadStringFromFile ----------------------------------------------------------- Creates a base64 string of an X.509 certificate file. ### VBA/VB6 Syntax `Public Declare Function X509_ReadStringFromFile Lib "diCrPKI.dll" (ByVal strOutput As String, ByVal nOutChars As Long, ByVal strCertFile As String, ByVal nOptions As Long) As Long` `nRet = X509_ReadStringFromFile(strOutput, nOutChars, strCertFile, nOptions) As Long` ### C/C++ Syntax `long __stdcall X509_ReadStringFromFile(char *szOutput, long nOutChars, const char *szCertFile, long nOptions);` ### Parameters *szOutput* : [out] to receive the output. *nOutChars* : [in] specifying the length of the output string. *szCertFile* : [in] with name of X.509 certificate file. *nOptions* : [in] option flags: not used. Set to zero. ### Returns (VBA/C) If successful, the return value is a positive number indicating the number of characters in the output string; otherwise it returns a negative [error code](#errorcodes). ### VBA Wrapper Syntax Public Function [`x509ReadStringFromFile`](#VB_x509ReadStringFromFile) (szCertFile As String, Optional nOptions As Long = 0) As String ### .NET Equivalent [X509.ReadStringFromFile Method](#M_X509_ReadStringFromFile) ### C++ (STL) Equivalent static std::string [dipki::X509::ReadStringFromFile](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_x509.html#a44e353950105afd924a2b2cdede7e956 "External link") (const std::string &certFile) ### Python Equivalent static [X509.read_string_from_file](https://cryptosys.net/pki/pydocpki/class-stubs/X509.html#cryptosyspki.X509.read_string_from_file "External link")(certfilename) ### Remarks For the "raw" VBA/C function, the user must allocate an output string buffer *szOutput* of the required length. Specify a zero *nOutChars* or an empty string for *szOutput* to find the required length. ANSI C users [must add one to this value](#cusersaddone) when allocating memory. This function reads in the complete X.509 certificate as a continuous base64 string. The same certificate will *always* produce exactly the same string. This string can be used, for example, when creating an XML file which requires the certificate as an attribute, e.g. ``` ``` The output string must be long enough to receive the *complete* output or a `SHORT_BUF_ERROR` error will result. ### Example (VBA core function) This example reads in the base64 string from the SAT Mexico test certificate and displays it. It then saves the string as a new certificate and uses the [`X509_CertThumb`](#X509_CertThumb) function to check that the two files are identical. ``` Dim nRet As Long Dim strCertString As String Dim strCertFile As String Dim strNewFile As String Dim strThumb1 As String Dim strThumb2 As String strCertFile = "aaa010101aaa_CSD.cer" ' Read in certificate file's data to a string nRet = X509_ReadStringFromFile("", 0, strCertFile, 0) Debug.Print "X509_ReadStringFromFile returns " & nRet If nRet <= 0 Then Exit Sub ' ERROR strCertString = String(nRet, " ") nRet = X509_ReadStringFromFile(strCertString, Len(strCertString), strCertFile, 0) Debug.Print "For certificate '" & strCertFile & "':" Debug.Print strCertString ' Save the string to a new certificate file, this time in PEM format strNewFile = "aaa010101aaa_CSD.pem.cer" nRet = X509_SaveFileFromString(strNewFile, strCertString, PKI_X509_FORMAT_PEM) Debug.Print "X509_SaveFileFromString returns " & nRet If nRet = 0 Then Debug.Print "Created new certificate file '" & strNewFile & "'" End If ' Check that the two certificate files are identical by computing their SHA-1 thumbprints strThumb1 = String(PKI_SHA1_CHARS, " ") strThumb2 = String(PKI_SHA1_CHARS, " ") nRet = X509_CertThumb(strCertFile, strThumb1, Len(strThumb1), 0) nRet = X509_CertThumb(strNewFile, strThumb2, Len(strThumb2), 0) Debug.Print "SHA-1(old)=" & strThumb1 Debug.Print "SHA-1(new)=" & strThumb2 If strThumb1 = strThumb2 Then Debug.Print "Certificates are identical" Else Debug.Print "ERROR: certificates do not match" End If ``` The output should look like this (the 1152-character certificate string has been edited) ``` X509_ReadStringFromFile returns 1152 For certificate 'aaa010101aaa_CSD.cer': MIIDWjCCAkKgAwIBAgIUMDAwMDEx...7D5F8SB7Li3zt9vbbMzBc5xGg== X509_SaveFileFromString returns 0 Created new certificate file 'aaa010101aaa_CSD.pem.cer' SHA-1(old)=5791650d63340129568c1eecc6566b2fdd8bbd4c SHA-1(new)=5791650d63340129568c1eecc6566b2fdd8bbd4c Certificates are identical ``` ### Example (VBA wrapper function) ``` Dim strCertString As String strCertString = x509ReadStringFromFile("AliceRSASignByCarl.cer") Debug.Print strCertString Debug.Print "CertThumb=" & x509CertThumb(strCertString) strCertString = x509ReadCertStringFromP7Chain("alice_bob_carl_certs.p7c", 3) Debug.Print strCertString Debug.Print "CertThumb=" & x509CertThumb(strCertString) Debug.Print "HashIssuerAndSN=" & x509HashIssuerAndSN(strCertString, PKI_HASH_SHA256) ``` ### See Also [X509_SaveFileFromString](#X509_SaveFileFromString) [[Contents](#topofpage)] [[Index](#index)] X509_SaveFileFromString ----------------------------------------------------------- Creates an X.509 certificate file from its base64 string representation. ### VBA/VB6 Syntax `Public Declare Function X509_SaveFileFromString Lib "diCrPKI.dll" (ByVal strNewCertFile As String, ByVal strCertString As String, ByVal nOptions As Long) As Long` `nRet = X509_SaveFileFromString(strNewCertFile, strCertString, nOptions)` ### C/C++ Syntax `long __stdcall X509_SaveFileFromString(const char *szNewCertFile, const char *szCertString, long nOptions);` ### Parameters *szNewCertFile* : [in] with name of X.509 certificate file to be created. *szCertString* : [in] containing the base64 representation of the certificate. *nOptions* : [in] option flags: `PKI_X509_FORMAT_PEM` to save the certificate in PEM format (default = DER-encoded binary) ### Returns (VBA/C) If successful, the return value is zero; otherwise it returns a negative [error code](#errorcodes). ### .NET Equivalent [X509.SaveFileFromString Method](#M_X509_SaveFileFromString) ### C++ (STL) Equivalent static int [dipki::X509::SaveFileFromString](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_x509.html#aafcc3aa7a6a076b7f8f4dcb207e62fe4 "External link") (const std::string &newCertFile, const std::string &certString, bool inPEMFormat=false) ### Python Equivalent static [X509.save_file_from_string](https://cryptosys.net/pki/pydocpki/class-stubs/X509.html#cryptosyspki.X509.save_file_from_string "External link")(newcertfile, certstring, in_pem_format=False) ### Remarks This function creates a new X.509 certificate file from a base64 string. It is the reverse of [`X509_ReadStringFromFile()`](#X509_ReadStringFromFile). Any existing file of the same name will be overwritten without warning. The default option (`nOptions = 0`) is to save the file in binary (BER, DER) format. A PEM format file will start with `-----BEGIN CERTIFICATE-----` and will contain the same base64 characters as in the certificate string. Both formats should be equally readable with the usual certificate manager programs and both should have the same message digest "thumbprint". ### Example See the example in [`X509_ReadStringFromFile`](#X509_ReadStringFromFile). ### See Also [X509_ReadStringFromFile](#X509_ReadStringFromFile) [[Contents](#topofpage)] [[Index](#index)] X509_TextDump --------------------------------------- Dumps details of an X.509 certificate (or a X.509 certificate revocation list (CRL) or a PKCS-10 certificate signing request (CSR)) to a text file. ### VBA/VB6 Syntax `Public Declare Function X509_TextDump Lib "diCrPKI.dll" (ByVal strFileOut As String, ByVal strCertFile As String, ByVal nOptions As Long) As Long` `nRet = X509_TextDump(strFileOut, strCertFile, nOptions)` ### C/C++ Syntax `long __stdcall X509_TextDump(const char *szFileOut, const char *szCertFile, long nOptions);` ### Parameters *szFileOut* : [in] with the filename of text file to be created. *szCertFile* : [in] with the filename of Certificate file (or [base64 representation](#base64forcert)). *nOptions* : [in] option flags: `PKI_X509_LATIN1` to try and convert UTF-8 attribute strings to Latin-1 (for display purposes). `PKI_X509_UTF8` to output attribute strings encoded in UTF-8 *[New in v20.3]* `PKI_X509_LDAP` to output the distinguished name in [LDAP string representation](#ldapstring). `PKI_X509_DECIMAL` to output the serial number in decimal format instead of hexadecimal. ### Returns (VBA/C) If successful, the return value is zero; otherwise it returns a nonzero [error code](#errorcodes). ### .NET Equivalent [X509.TextDump Method](#M_X509_TextDump) ### Python Equivalent static [X509.text_dump](https://cryptosys.net/pki/pydocpki/class-stubs/X509.html#cryptosyspki.X509.text_dump "External link")(outputfile, certfile, opts=0) ### Remarks The input file may be in binary BER/DER format or base64 PEM file format, or may be passed in [base64 representation](#base64forcert) or as a [PEM string](#pemstring). It produces a text file containing the basic details of an X.509 certificate, X.509 certificate revocation list (CRL) or PKCS-10 certificate signing request (CSR). *[New in v12.3]* The notation `[!]` denotes a critical extension, e.g. `Key Usage[!]:`. ### Example ``` Dim nRet As Long Dim strInputFile As String Dim strOutFile As String strInputFile = "AliceRSASignByCarl.cer" strOutFile = "dump-AliceRSASignByCarl.cer.txt" Debug.Print "File=" & strInputFile nRet = X509_TextDump(strOutFile, strInputFile, 0) Debug.Print "X509_TextDump returns " & nRet ``` The above example produces a text file with the following contents: ``` X.509 CERTIFICATE Version: 3 Serial Number: #x46346BC7800056BC11D36E2EC410B3B0 Issuer: CN=CarlRSA Subject: CN=AliceRSA Validity: NotBefore: 1999-09-19T01:08:47Z NotAfter: 2039-12-31T23:59:59Z Subject Public Key Algorithm: rsaEncryption RSA key length: 1024 bits Modulus: E0 89 73 39 8D D8 F5 F5 E8 87 76 39 7F 4E B0 05 BB 53 83 DE 0F B7 AB DC 7D C7 75 29 0D 05 2E 6D 12 DF A6 86 26 D4 D2 6F AA 58 29 FC 97 EC FA 82 51 0F 30 80 BE B1 50 9E 46 44 F1 2C BB D8 32 CF C6 68 6F 07 D9 B0 60 AC BE EE 34 09 6A 13 F5 F7 05 05 93 DF 5E BA 35 56 D9 61 FF 19 7F C9 81 E6 F8 6C EA 87 40 70 EF AC 6D 2C 74 9F 2D FA 55 3A B9 99 77 02 A6 48 52 8C 4E F3 57 38 57 74 57 5F Exponent: 01 00 01 X509v3 Extensions: Subject Type: End Entity Key Usage[!]: digitalSignature,nonRepudiation Authority Key Identifier: e9e09027ac78207a9ad34cf242374e22ae9e38bb Subject Key Identifier: 77d2b4d1b74c8a8aa3ce459dceec3ca03ae3ff50 Subject Alternative Name: RFC822 Name: AliceRSA@example.com Signature Algorithm: sha1WithRSAEncryption Signature Hash Algorithm: sha1 Signature Value: 3E 70 47 A8 48 CC 13 58 8F CA 51 71 6B 4E 36 18 5D 04 7E 80 B1 8D 4D CC CA A3 8F CC 7D 56 C8 BC CF 6E B3 1C 59 A9 20 AA 05 81 A8 4E 25 AD A7 70 14 75 2F F5 C7 9B D1 0E E9 63 D2 64 B7 C6 66 6E 73 21 54 DF F4 BA 25 5D 7D 49 D3 94 6B 22 36 74 73 B8 4A EC 2F 64 ED D3 3D D2 A7 42 C5 E8 37 8A B4 DB 9F 67 E4 BD 9F F9 FE 74 EF EA F9 EE 63 6A D8 3F 4B 25 09 B5 D8 1A 76 AE EB 9B DB 49 B0 22 SHA-1 Thumbprint: b30c48855055c2e64ce3196492d4b83831a6b3cb SHA-256 Thumbprint: 10e79a9993c26a87f2109ec1e81e0ac3ada0ee1bac1fe57fd85450e2c7c2406b ``` ### See Also [X509_QueryCert](#X509_QueryCert) [ASN1_TextDump](#ASN1_TextDump) [[Contents](#topofpage)] [[Index](#index)] X509_TextDumpToString ------------------------------------------------------- Dumps details of an X.509 certificate or a X.509 certificate revocation list (CRL) or a PKCS-10 certificate signing request (CSR) to a string. ### VBA/VB6 Syntax `Public Declare Function X509_TextDumpToString Lib "diCrPKI.dll" (ByVal strOutput As String, ByVal nOutChars As Long, ByVal strCertFile As String, ByVal nOptions As Long) As Long` `nRet = X509_TextDumpToString(strOutput, nOutChars, strCertFile, nOptions)` ### C/C++ Syntax `long __stdcall X509_TextDumpToString(char *szOutput, long nOutChars, const char *szCertFile, long nOptions);` ### Parameters *szOutput* : [out] String buffer to receive output. *nOutChars* : [in] Maximum number of characters to be received. *szCertFile* : [in] Name of input file (or its [base64](#base64forcert) or [PEM string](#pemstring) representation). *nOptions* : [in] option flags: `PKI_X509_LATIN1` to try and convert UTF-8 attribute strings to Latin-1 (for display purposes). `PKI_X509_UTF8` to output attribute strings encoded in UTF-8 (C/C++ only) *[New in v20.3]* `PKI_X509_LDAP` to output the distinguished name in [LDAP string representation](#ldapstring). `PKI_X509_DECIMAL` to output the serial number in decimal format instead of hexadecimal. ### Returns (VBA/C) If successful, the return value is the number of characters in or required for the output string; otherwise it returns a negative [error code](#errorcodes). ### VBA Wrapper Syntax Public Function [`x509TextDumpToString`](#VB_x509TextDumpToString) (szCertFile As String, Optional nOptions As Long = 0) As String ### .NET Equivalent [X509.TextDumpToString Method](#M_X509_TextDumpToString) ### C++ (STL) Equivalent static std::string [dipki::X509::TextDumpToString](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_x509.html#a9b8039568d9cd27430a5809956f06ed4 "External link") (const std::string &certFile, OutputOpts outOpts=OutputOpts::Default_OutputOpt) ### Python Equivalent static [X509.text_dump_tostring](https://cryptosys.net/pki/pydocpki/class-stubs/X509.html#cryptosyspki.X509.text_dump_tostring "External link")(certfile, opts=0) ### Remarks For the "raw" VBA/C function, the user must allocate an output string buffer *szOutput* of the required length. Specify a zero *nOutChars* or an empty string for *szOutput* to find the required length. ANSI C users [must add one to this value](#cusersaddone) when allocating memory. The input file may be a an X.509 certificate, X.509 certificate revocation list (CRL) or PKCS-10 certificate signing request (CSR) and may be a file in binary BER/DER or base64 PEM file format, or may be passed in [base64 representation](#base64forcert) or as a [PEM string](#pemstring). The output string must be long enough to receive the *complete* output or a `SHORT_BUF_ERROR` error will result. ### Example (VBA core function) ``` Dim strInputFile As String Dim strBuffer As String Dim nChars As Long strInputFile = "AliceRSASignByCarl.cer" Debug.Print "File=" & strInputFile ' Query for required length nChars = X509_TextDumpToString("", 0, strInputFile, PKI_X509_DECIMAL) Debug.Print "X509_TextDumpToString returns " & nChars ' Dimension output buffer strBuffer = String(nChars, " ") nChars = X509_TextDumpToString(strBuffer, Len(strBuffer), strInputFile, PKI_X509_DECIMAL) Debug.Print strBuffer ``` ``` File=AliceRSASignByCarl.cer X509_TextDumpToString returns 1692 X.509 CERTIFICATE Version: 3 Serial Number: 93318145165434344057210696409401045936 Issuer: CN=CarlRSA ...[cut]... ``` ### Example (VBA wrapper function) ``` Debug.Print x509TextDumpToString("AliceRSASignByCarl.cer") Debug.Print x509QueryCert("AliceRSASignByCarl.cer", "subjectName") Debug.Print asn1TextDumpToString("AliceRSASignByCarl.cer") ``` ### See Also [X509_QueryCert](#X509_QueryCert) [ASN1_TextDump](#ASN1_TextDump) [[Contents](#topofpage)] [[Index](#index)] X509_ValidatePath ----------------------------------------------- Validates a certificate path. ### VBA/VB6 Syntax `Public Declare Function X509_ValidatePath Lib "diCrPKI.dll" (ByVal strCertListOrP7File As String, ByVal strTrustedCert As String, ByVal nOptions As Long) As Long` `nRet = X509_ValidatePath(strCertListOrP7File, strTrustedCert, nOptions)` ### C/C++ Syntax `long __stdcall X509_ValidatePath(const char *szCertListOrP7File, const char *szTrustedCert, long nOptions);` ### Parameters *szCertListOrP7File* : [in] either a list of certificate names separated by a semicolon or the name of a PKCS-7 "certs-only" file containing the certificates to be validated. *szTrustedCert* : [in] name of the trusted certificate (or [base64 representation](#base64forcert)). *nOptions* : [in] option flags: `PKI_X509_NO_TIMECHECK` to avoid checking if the certificates are valid now (default = check validity dates against system clock). ### Returns (VBA/C) Zero (0) if the certification path is valid. If the certificates are otherwise of correct format but the validation fails, the return value is `PKI_X509_INVALID` (+43 = `CERT_PATH_ERROR`); otherwise a *negative* [error code](#errorcodes). ### .NET Equivalent [X509.ValidatePath Method](#M_X509_ValidatePath) (String) ### Python Equivalent static [X509.cert_path_is_valid](https://cryptosys.net/pki/pydocpki/class-stubs/X509.html#cryptosyspki.X509.cert_path_is_valid "External link")(certlist, trustedcert="", no_timecheck=False) ### Remarks A basic validation is carried out confirming that the subject of certificate `x` is the issuer of certificate `x+1`, that certficate `x` was signed by certificate `x-1`, and that each certificate is valid as at the time on the system clock. Only distinguished names are used to identify subjects and issuers, not alternative names or IDs. Certificate policies are ignored and no checks are made for revocation (use [`X509_CheckCertInCRL()`](#X509_CheckCertInCRL) individually). The order of the certificates in the input list is not important, but a complete chain must exist. Note that the certificates must either all exist inside one .p7c cert chain file, or exist individually as .cer files. In the latter case, specify all the file names in a semi-colon-separated list. You can also pass the individual certificate information in its base64 representation rather than filenames, as in `szCertList="MIHgMIGaAgE...se348UN/Q=;MIHgMIGaAgEB...9j8eEtvHw=;...etc`. The *szTrustedCert* parameter is required unless a self-signed trust anchor is included in the list. If there is no self-signed certificate, then you must specify a trusted certificate which has signed the certificate at the top of your chain. If specified, this must exist separately as a .cer file. All certificates must be valid at the time the check is made or an error will result, unless the `PKI_X509_NO_TIMECHECK` option is used. More information on the reason for an invalid certification path may be available by using [`PKI_LastError()`](#PKI_LastError). *[Changed in v12.0]* If the certificates are otherwise of correct format but the validation fails, this function returns `CERT_PATH_ERROR` (+43). Previous versions would return +1. ### Example ``` Dim nRet As Long Dim strP7cFile As String Dim strTrustedCert As String Dim strCertList As String ' A p7c "certs-only" file which includes a self-signed cert strP7cFile = "testcerts1.p7c" nRet = X509_ValidatePath(strP7cFile, "", 0) Debug.Print "X509_ValidatePath returns " & nRet & " (expected 0)" ' Same again but specify the trusted root cert ' (which is the same as the self-signed cert in the p7c file) strP7cFile = "testcerts1.p7c" strTrustedCert = "testcert00.cer" nRet = X509_ValidatePath(strP7cFile, strTrustedCert, 0) Debug.Print "X509_ValidatePath returns " & nRet & " (expected 0)" ' Specify a cert list - testcert00.cer is the self-signed cert strCertList = "testcert00.cer;testcert03.cer;testcert01.cer;testcert02.cer" nRet = X509_ValidatePath(strCertList, "", 0) Debug.Print "X509_ValidatePath returns " & nRet & " (expected 0)" ' Same again but specify the trusted root cert (this time it is not in the list) strCertList = "testcert01.cer;testcert02.cer;testcert03.cer" strTrustedCert = "testcert00.cer" nRet = X509_ValidatePath(strCertList, strTrustedCert, 0) Debug.Print "X509_ValidatePath returns " & nRet & " (expected 0)" ``` ### See Also [X509_VerifyCert](#X509_VerifyCert) [X509_CertIsValidNow](#X509_CertIsValidNow) [X509_CheckCertInCRL](#X509_CheckCertInCRL) [[Contents](#topofpage)] [[Index](#index)] X509_VerifyCert ------------------------------------------- Verifies that an X.509 certificate - or X.509 certificate revocation list (CRL) or PKCS-10 certificate signing request (CSR) - has been signed by its issuer. ### VBA/VB6 Syntax `Public Declare Function X509_VerifyCert Lib "diCrPKI.dll" (ByVal strCertToVerify As String, ByVal strIssuerCert As String, ByVal nOptions As Long) As Long` `nRet = X509_VerifyCert(strCertToVerify, strIssuerCert, nOptions)` ### C/C++ Syntax `long __stdcall X509_VerifyCert(const char *szCertToVerify, const char *szIssuerCert, long nOptions);` ### Parameters *szCertToVerify* : [in] Name of the file to be verified (or a [PEM string](#pemstring)). *szIssuerCert* : [in] Name of the issuer's certificate file (or a [PEM string](#pemstring)). Leave empty `""` for a PKCS#10 CSR. *nOptions* : [in] option flags: not used in this release. Specify zero. ### Returns (VBA/C) Zero (0) if the certificate's signature is valid. If the certificate is otherwise of correct format but the validation fails, the return value is `PKI_X509_VERIFY_FAILURE` (+22 = `SIGNATURE_ERROR`); otherwise it returns a *positive* [error code](#errorcodes). ### .NET Equivalent [X509.VerifyCert Method](#M_X509_VerifyCert) ### Python Equivalent static [X509.cert_is_verified](https://cryptosys.net/pki/pydocpki/class-stubs/X509.html#cryptosyspki.X509.cert_is_verified "External link")(certfile, issuercert) ### Remarks This function verifies only that the certificate was signed by the owner of the public key in the issuer's certificate. It does not check the validity dates of either certificate (to do that use [`X509_CertIsValidNow()`](#X509_CertIsValidNow)). Nor does it check that the certficate has been revoked (to do that use [`X509_CheckCertInCRL()`](#X509_CheckCertInCRL)). Only certificates signed with supported signature algorithms can be checked: see [Supported Algorithms](#SupportedAlgorithms). The certificate file may be in binary BER/DER format or base64 PEM file format, or may be passed in [base64 representation](#base64forcert) or as a [PEM string](#pemstring). This function can also be used to verify that an X.509 Certificate Revocation List (CRL) has been signed by the owner of the issuer's certificate or that the self-signed signature in a PKCS#10 Certificate Signing Request (CSR) is valid. Just pass the name of the file (or its PEM string form) as *szCertToVerify*. *[New in v12.0]* A PKCS#10 Certificate Signing Request (CSR) contains its own public key which it can use to verify its own signature directly. To verify a CSR, pass its name in *szCertToVerify* and set *szIssuerCert*`=""`. See example below. *[Changed in v12.0]* If the certificate is otherwise of correct format but the validation fails, this function returns `SIGNATURE_ERROR` (22). Previous versions would return -1. ### Example This example verifies that the certificate `myuser.cer` has been signed by the owner of `myca.cer`. ``` ' Returns 0 if OK, PKI_X509_VERIFY_FAILURE if fails to validate, or +ve other error Dim nRet As Long nRet = X509_VerifyCert("myuser.cer", "myca.cer", 0) If nRet = 0 Then Debug.Print "Verification is OK" ElseIf nRet = PKI_X509_VERIFY_FAILURE Then Debug.Print "Cert not issued by this Issuer" Else Debug.Print "Error: " & nRet & pkiGetLastError() End If ``` This example verifies the signature in a PKCS#10 Certificate Signing Request. ``` Dim nRet As Long nRet = X509_VerifyCert("myreq.p10.txt", "", 0) If nRet = 0 Then Debug.Print "Verification is OK" ElseIf nRet = PKI_X509_VERIFY_FAILURE Then Debug.Print "Signature is invalid" Else Debug.Print "Error: " & nRet & pkiGetLastError() End If ``` ### See Also [X509_CertIsValidNow](#X509_CertIsValidNow) [X509_ValidatePath](#X509_ValidatePath) [X509_CheckCertInCRL](#X509_CheckCertInCRL) [[Contents](#topofpage)] [[Index](#index)] XOF_Bytes ------------------------------- Generate bytes using an extendable output function (XOF). ### VBA/VB6 Syntax `Public Declare Function XOF_Bytes Lib "diCrPKI.dll" (ByRef lpOutput As Byte, ByVal nOutBytes As Long, ByRef lpMessage As Byte, ByVal nMsgLen As Long, ByVal nOptions As Long) As Long` `nRet = XOF_Bytes(abOutput(0), nOutBytes, abMessage(0), nMsgLen, nOptions) ' Note the "(0)" after the byte array parameters` ### C/C++ Syntax `long __stdcall XOF_Bytes(unsigned char *lpOutput, long nOutBytes, const void *lpMessage, long nMsgLen, long nOptions);` ### Parameters *lpOutput* : [out] byte buffer to receive the output. *nOutBytes* : [in] size of output buffer in bytes. *lpMessage* : [in] byte array containing the input data. *nMsgLen* : [in] length of the input data in bytes. *nOptions* : [in] Option flags. Select one of: `PKI_XOF_SHAKE128` to use SHAKE128 `PKI_XOF_SHAKE256` to use SHAKE256 `PKI_XOF_MGF1_SHA1` to use MGF1-SHA-1 `PKI_XOF_MGF1_SHA256` to use MGF1-SHA-256 `PKI_XOF_MGF1_SHA512` to use MGF1-SHA-512 ### Returns (VBA/C) If successful, the return value is the number of bytes in the output; otherwise it returns a negative [error code](#errorcodes). ### VBA Wrapper Syntax Public Function [`xofBytes`](#VB_xofBytes) (nBytes As Long, lpMessage() As Byte, nOptions As Long) As Byte() ### .NET Equivalent [Xof.Bytes Method](#M_Xof_Bytes) ### C++ (STL) Equivalent static bvec_t [dipki::Xof::Bytes](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_xof.html#a55cd586acc417fe248d8568bed801766 "External link") (int numBytes, const bvec_t &message, XofAlg xofalg) ### Python Equivalent static [Xof.bytes](https://cryptosys.net/pki/pydocpki/class-stubs/Xof.html#cryptosyspki.Xof.bytes "External link")(numbytes, msg, xofalg) ### Remarks The output buffer *lpOutput* must exist. It will be filled with exactly *nOutBytes* bytes. Note there is no zero option for *nOptions*: a valid option flag must be specified. SHAKE128 and SHAKE256 are described in [[FIPS202](#FIPS202)]. MGF1, despite its name as a *Mask Generation Function* (MGF), is also an eXtendable Output Function (XOF) using the SHA1/SHA-2 hash functions, and is described in [[PKCS1](#PKCS1)]. ### Example (VBA core function) ``` Dim strMsgHex As String Dim nOutBits As Long Dim nOutBytes As Long Dim abOut() As Byte Dim abMsg() As Byte Dim nMsgLen As Long Dim strOK As String Dim nRet As Long ' Ref: "SHA-3 XOF Test Vectors for Byte-Oriented Output" ' File `SHAKE256VariableOut.rsp` COUNT = 1244 ' ' Input in hex form strMsgHex = "6ae23f058f0f2264a18cd609acc26dd4dbc00f5c3ee9e13ecaea2bb5a2f0bb6b" nOutBits = 2000 strOK = "b9b92544fb25cfe4ec6fe437d8da2bbe00f7bdaface3de97b8775a44d753c3adca3f7c6f183cc8647e229070439aa9539ae1f8f13470c9d3527fffdeef6c94f9f0520ff0c1ba8b16e16014e1af43ac6d94cb7929188cce9d7b02f81a2746f52ba16988e5f6d93298d778dfe05ea0ef256ae3728643ce3e29c794a0370e9ca6a8bf3e7a41e86770676ac106f7ae79e67027ce7b7b38efe27d253a52b5cb54d6eb4367a87736ed48cb45ef27f42683da140ed3295dfc575d3ea38cfc2a3697cc92864305407369b4abac054e497378dd9fd0c4b352ea3185ce1178b3dc1599df69db29259d4735320c8e7d33e8226620c9a1d22761f1d35bdff79a" ' Convert to byte array form abMsg = cnvBytesFromHexStr(strMsgHex) nMsgLen = UBound(abMsg) + 1 nOutBytes = (nOutBits / 8) ReDim abOut(nOutBytes - 1) nRet = XOF_Bytes(abOut(0), nOutBytes, abMsg(0), nMsgLen, PKI_XOF_SHAKE256) If nRet > 0 Then Debug.Print "OUT=" & cnvHexStrFromBytes(abOut) Debug.Print "OK =" & strOK Else Debug.Print "Error code " & nRet End If ``` This should result in output as follows: ``` OUT=B9B92544FB25CFE4EC6FE437D8DA2BBE00F7BDAFACE3DE97B8775A44D753C3ADCA3F7C6F183CC8647E229070439AA9539AE1F8F13470C9D3527FFFDEEF6C94F9F0520FF0C1BA8B16E16014E1AF43AC6D94CB7929188CCE9D7B02F81A2746F52BA16988E5F6D93298D778DFE05EA0EF256AE3728643CE3E29C794A0370E9CA6A8BF3E7A41E86770676AC106F7AE79E67027CE7B7B38EFE27D253A52B5CB54D6EB4367A87736ED48CB45EF27F42683DA140ED3295DFC575D3EA38CFC2A3697CC92864305407369B4ABAC054E497378DD9FD0C4B352EA3185CE1178B3DC1599DF69DB29259D4735320C8E7D33E8226620C9A1D22761F1D35BDFF79A OK =b9b92544fb25cfe4ec6fe437d8da2bbe00f7bdaface3de97b8775a44d753c3adca3f7c6f183cc8647e229070439aa9539ae1f8f13470c9d3527fffdeef6c94f9f0520ff0c1ba8b16e16014e1af43ac6d94cb7929188cce9d7b02f81a2746f52ba16988e5f6d93298d778dfe05ea0ef256ae3728643ce3e29c794a0370e9ca6a8bf3e7a41e86770676ac106f7ae79e67027ce7b7b38efe27d253a52b5cb54d6eb4367a87736ed48cb45ef27f42683da140ed3295dfc575d3ea38cfc2a3697cc92864305407369b4abac054e497378dd9fd0c4b352ea3185ce1178b3dc1599df69db29259d4735320c8e7d33e8226620c9a1d22761f1d35bdff79a ``` ### Example (VBA wrapper function) ``` Dim lpMessage() As Byte Dim lpOut() As Byte lpMessage = cnvFromHex("6ae23f058f0f2264a18cd609acc26dd4dbc00f5c3ee9e13ecaea2bb5a2f0bb6b") ' Output 2000 bits lpOut = xofBytes(2000 \ 8, lpMessage, PKI_XOF_SHAKE256) Debug.Print "OUT=" & cnvToHex(lpOut) Debug.Print "OK =" & "b9b92544fb25cf...f1d35bdff79a" ' MGF1-SHA-256 lpMessage = cnvFromHex("3b5c056af3ebba70d4c805380420585562b32410a778f558ff951252407647e3") Debug.Print cnvToHex(lpMessage) lpOut = xofBytes(34, lpMessage, PKI_XOF_MGF1_SHA256) Debug.Print "OUT=" & cnvToHex(lpOut) Debug.Print "OK =" & "5b7eb772aecf04c74af07d9d9c1c1f8d3a90dcda00d5bab1dc28daecdc86eb87611e" ``` ### See Also [`PRF_Bytes`](#PRF_Bytes) [[Contents](#topofpage)] [[Index](#index)] VBA Wrapper Functions ----------------------------------------------------- The wrapper functions for VBA/VB6 programmers are now all in `basCrPKI.bas`. See [Notes on VBA wrapper functions](#notesonvbawrapperfunctions). ### VBA Wrapper Function List * [asn1TextDumpToString](#VB_asn1TextDumpToString) - Dump details of ASN.1 formatted data to a string. * [asn1Type](#VB_asn1Type) - Describe the type of ASN.1 data. * [cipherDecryptAEAD](#VB_cipherDecryptAEAD) - Decrypt data using Authenticated Encryption with Associated Data (AEAD). * [cipherDecryptBytes](#VB_cipherDecryptBytes) - Decrypts data in a byte array using the specified block cipher algorithm, mode and padding. * [cipherDecryptHex](#VB_cipherDecryptHex) - Decrypt hex-encoded data using the specified block cipher algorithm, mode and padding. * [cipherEncryptAEAD](#VB_cipherEncryptAEAD) - Encrypt data using Authenticated Encryption with Associated Data (AEAD). * [cipherEncryptBytes](#VB_cipherEncryptBytes) - Encrypt data in a byte array using the specified block cipher algorithm, mode and padding. * [cipherEncryptHex](#VB_cipherEncryptHex) - Encrypt hex-encoded data using the specified block cipher algorithm, mode and padding. * [cipherFileDecrypt](#VB_cipherFileDecrypt) - Decrypt a file. * [cipherFileEncrypt](#VB_cipherFileEncrypt) - Encrypt a file. * [cipherKeyUnwrap](#VB_cipherKeyUnwrap) - Unwraps (decrypts) key material with a key-encryption key. * [cipherKeyWrap](#VB_cipherKeyWrap) - Wraps (encrypts) key material with a key-encryption key. * [cmsGetSigDataDigest](#VB_cmsGetSigDataDigest) - Extract the message digest from a signed-data CMS object file and verify the signature. * [cmsMakeEnvData](#VB_cmsMakeEnvData) - Create a CMS enveloped-data object for one or more recipients. * [cmsMakeEnvDataFromBytes](#VB_cmsMakeEnvDataFromBytes) - Create a CMS enveloped-data object from data in a byte array. * [cmsMakeEnvDataFromString](#VB_cmsMakeEnvDataFromString) - Create a CMS enveloped-data object from an ASCII string. * [cmsMakeSigData](#VB_cmsMakeSigData) - Create a CMS signed-data object from an input data file. * [cmsMakeSigDataFromBytes](#VB_cmsMakeSigDataFromBytes) - Create a CMS signed-data object from data in a byte array. * [cmsMakeSigDataFromSigValue](#VB_cmsMakeSigDataFromSigValue) - Create a CMS signed-data object using a pre-computed signature value. * [cmsMakeSigDataFromString](#VB_cmsMakeSigDataFromString) - Create a CMS signed-data object from data in a string. * [cmsQueryEnvData](#VB_cmsQueryEnvData) - Query a CMS enveloped-data object file for selected information. * [cmsQuerySigData](#VB_cmsQuerySigData) - Query a CMS signed-data object file for selected information. * [cmsReadEnvDataToBytes](#VB_cmsReadEnvDataToBytes) - Read and decrypt a CMS enveloped-data object to a byte array. * [cmsReadEnvDataToString](#VB_cmsReadEnvDataToString) - Read and decrypt a CMS enveloped-data object to a string. * [cmsReadSigDataToBytes](#VB_cmsReadSigDataToBytes) - Read the content from a CMS signed-data object directly into a byte array. * [cmsReadSigDataToString](#VB_cmsReadSigDataToString) - Read the content from a CMS signed-data object directly into a string. * [cmsVerifySigData](#VB_cmsVerifySigData) - Verify the signature and content of a signed-data CMS object file. * [cnvB64Filter](#VB_cnvB64Filter) - Strip any invalid base64 characters from a string. * [cnvB64StrFromBytes](#VB_cnvB64StrFromBytes) - Encode an array of bytes as a base64-encoded string. * [cnvB64StrFromHexStr](#VB_cnvB64StrFromHexStr) - Re-encode a hexadecimal-encoded binary value as base64. * [cnvB64StrFromString](#VB_cnvB64StrFromString) - Encode an ANSI string as a base64-encoded string. * [cnvBase58FromBytes](#VB_cnvBase58FromBytes) - Convert 8-bit binary data to equivalent base58-encoded string format. * [cnvBase58ToBytes](#VB_cnvBase58ToBytes) - Convert a base58-encoded string to an equivalent array of 8-bit unsigned integers. * [cnvByteEncoding](#VB_cnvByteEncoding) - Convert encoding of byte array between UTF-8 and Latin-1. * [cnvBytesFromB64Str](#VB_cnvBytesFromB64Str) - Decode a base64-encoded string as an array of Bytes. * [cnvBytesFromHexStr](#VB_cnvBytesFromHexStr) - Decode a hexadecimal-encoded string as an array of Bytes. * [cnvBytesLen](#VB_cnvBytesLen) - Find length of byte array. * [cnvBytesMid](#VB_cnvBytesMid) - Return a substring of bytes of specified length from within a given byte array * [cnvCheckUTF8Bytes](#VB_cnvCheckUTF8Bytes) - Check if a byte array contains valid UTF-8 characters. * [cnvFromBase64](#VB_cnvFromBase64) - Decodes a base64-encoded string as an array of bytes. * [cnvFromHex](#VB_cnvFromHex) - Decodes a hexadecimal-encoded string as an array of bytes. * [cnvHexFilter](#VB_cnvHexFilter) - Strip any invalid hex characters from a hex string. * [cnvHexFromBytesMid](#VB_cnvHexFromBytesMid) - Encode a substring of an array of bytes as a hexadecimal-encoded string. * [cnvHexStrFromB64Str](#VB_cnvHexStrFromB64Str) - Re-encode a base64-encoded binary value as hexadecimal. * [cnvHexStrFromBytes](#VB_cnvHexStrFromBytes) - Encode an array of bytes as a hexadecimal-encoded string. * [cnvHexStrFromString](#VB_cnvHexStrFromString) - Encode an ANSI string as a hexadecimal-encoded string. * [cnvLatin1FromUTF8Bytes](#VB_cnvLatin1FromUTF8Bytes) - Convert UTF-8 encoded array of bytes into a Latin-1 string, if possible. * [cnvNumFromBytes](#VB_cnvNumFromBytes) - Convert the leftmost four bytes of an array to a 32-bit integer. * [cnvNumToBytes](#VB_cnvNumToBytes) - Convert a 32-bit integer to an array of 4 bytes. * [cnvReverseBytes](#VB_cnvReverseBytes) - Reverse the order of a byte array. * [cnvStringFromHexStr](#VB_cnvStringFromHexStr) - Decode a hexadecimal-encoded string as an ANSI string. * [cnvToBase64](#VB_cnvToBase64) - Encodes an array of bytes as a base64-encoded string. * [cnvToHex](#VB_cnvToHex) - Encodes an array of bytes as a hexadecimal-encoded string. * [cnvUTF8BytesFromLatin1](#VB_cnvUTF8BytesFromLatin1) - Convert a string of 8-bit Latin-1 (ISO-8859-1) characters into a UTF-8 encoded array of bytes. * [comprCompress](#VB_comprCompress) - Compress data using zlib compression. * [comprUncompress](#VB_comprUncompress) - Uncompress data using zlib compression. * [eccDHSharedSecret](#VB_eccDHSharedSecret) - Compute EC Diffie-Hellman (ECDH) shared secret. * [eccKeyHashCode](#VB_eccKeyHashCode) - Compute the hash code of an "internal" ECC public or private key string. * [eccMakeKeys](#VB_eccMakeKeys) - Generate an EC public/private key pair and save as two key files. * [eccPublicKeyFromPrivate](#VB_eccPublicKeyFromPrivate) - Convert an internal EC private key string into an internal EC public key string. * [eccQueryKey](#VB_eccQueryKey) - Query an EC key string for selected information. * [eccReadKeyByCurve](#VB_eccReadKeyByCurve) - Read an EC key from its hexadecimal representation. * [eccReadPrivateKey](#VB_eccReadPrivateKey) - Read an EC private key from a file into an internal key string. * [eccReadPublicKey](#VB_eccReadPublicKey) - Read an EC private key from a file into an internal key string. * [eccSaveEncKey](#VB_eccSaveEncKey) - Save an internal EC private key string to an encrypted key file. * [eccSaveKey](#VB_eccSaveKey) - Save an internal EC key string to a key file. * [errFormatErrorMessage](#VB_errFormatErrorMessage) - Return an error message string for the last error. * [hashBytes](#VB_hashBytes) - Compute hash digest in byte format of byte input. * [hashFile](#VB_hashFile) - Compute hash digest in byte format of a file. * [hashHexFromBytes](#VB_hashHexFromBytes) - Compute hash digest in hex format of byte input. * [hashHexFromFile](#VB_hashHexFromFile) - Compute hash digest in hex format of a file. * [hashHexFromHex](#VB_hashHexFromHex) - Compute hash digest in hex-encoded format from hex-encoded input. * [hashLength](#VB_hashLength) - Return length of message digest output in bytes. * [hmacBytes](#VB_hmacBytes) - Compute hash-based message authentication code (HMAC) as a byte array from byte data. * [hmacHexFromBytes](#VB_hmacHexFromBytes) - Compute hash-based message authentication code (HMAC) in hexadecimal format from byte data. * [hmacHexFromHex](#VB_hmacHexFromHex) - Compute hash-based message authentication code (HMAC) in hexadecimal format from data in hexadecimal-encoded strings. * [hpkeDerivePrivateKey](#VB_hpkeDerivePrivateKey) - Derive an EC private key in a deterministic manner from input keying material using the DeriveKeyPair algorithm in RFC9180. * [hpkeLabeledExpand](#VB_hpkeLabeledExpand) - Compute the output of the LabeledExpand function as defined in RFC9180. * [hpkeLabeledExtract](#VB_hpkeLabeledExtract) - Compute the output of the LabeledExtract function as defined in RFC9180. * [kdfBytes](#VB_kdfBytes) - Generate a key-encryption key (KEK) from input keying material (IKM) using a key derivation function (KDF). * [kdfForCms](#VB_kdfForCms) - Generate a key-encryption key (KEK) for ECDH key exchange in a CMS EnvelopedData object. * [ocspMakeRequest](#VB_ocspMakeRequest) - Create an Online Certification Status Protocol (OCSP) request as a base64 string. * [ocspReadResponse](#VB_ocspReadResponse) - Read a response to an Online Certification Status Protocol (OCSP) request and outputs the main results in text form. * [padBytesBlock](#VB_padBytesBlock) - Creates an input block suitably padded for encryption by a block cipher in ECB or CBC mode. * [padHexBlock](#VB_padHexBlock) - Creates a hex-encoded input block suitably padded for encryption by a block cipher in ECB or CBC mode. * [padUnpadBytes](#VB_padUnpadBytes) - Removes the padding from an encryption block. * [padUnpadHex](#VB_padUnpadHex) - Removes the padding from a hex-encoded encryption block. * [pbeKdf2](#VB_pbeKdf2) - Derives a key of any length from a password using the PBKDF2 algorithm from PKCS#5 v2.1. * [pbeKdf2Hex](#VB_pbeKdf2Hex) - Derives a hex-encoded key of any length from a password using the PBKDF2 algorithm from PKCS#5 v2.1. * [pbeScrypt](#VB_pbeScrypt) - Derives a key of any length from a password using the SCRYPT algorithm from RFC7914. * [pbeScryptHex](#VB_pbeScryptHex) - Derives a hex-encoded key of any length from a password using the SCRYPT algorithm from RFC7914. * [pfxMakeFile](#VB_pfxMakeFile) - Create a PFX (PKCS-12) file from an X.509 certificate and (optional) encrypted private key file. * [pkiCompileTime](#VB_pkiCompileTime) - Get date and time the CryptoSys PKI DLL module was last compiled. * [pkiErrorCode](#VB_pkiErrorCode) - Returns the error code of the error that occurred when calling the last function. * [pkiErrorLookup](#VB_pkiErrorLookup) - Get error message associated with a given error code. * [pkiLastError](#VB_pkiLastError) - Get last error message set by previous function. * [pkiLicenceType](#VB_pkiLicenceType) - Returns the ASCII value of the licence type. * [pkiModuleInfo](#VB_pkiModuleInfo) - Get additional information about the core DLL module. * [pkiModuleName](#VB_pkiModuleName) - Get path name of the current process's module. * [pkiPlatform](#VB_pkiPlatform) - Get platform the core DLL was compiled for. * [pkiVersion](#VB_pkiVersion) - Get version number of native core DLL. * [prfBytes](#VB_prfBytes) - Generate output bytes using a pseudorandom function (PRF). * [pwdPrompt](#VB_pwdPrompt) - Prompt for a password in a dialog box. * [rngBytes](#VB_rngBytes) - Generate random bytes. * [rngGuid](#VB_rngGuid) - Generate a random 36-character Global Unique IDentifier (GUID) string. * [rngInitialize](#VB_rngInitialize) - Initialize the RNG generator using a seed file. * [rngInitializeEx](#VB_rngInitializeEx) - Query and initialize the RNG generator using Intel(R) DRNG, if available. * [rsaDecodeMsg](#VB_rsaDecodeMsg) - Decode an EME or EMSA encoded message block according to PKCS#1. * [rsaDecrypt](#VB_rsaDecrypt) - Decrypt a message encrypted using an RSA encryption scheme. * [rsaEncodeMsg](#VB_rsaEncodeMsg) - Encode an EME or EMSA encoded message block according to PKCS#1. * [rsaEncrypt](#VB_rsaEncrypt) - Encrypt a short message using RSA encryption. * [rsaFromXMLString](#VB_rsaFromXMLString) - Create an RSA key string in internal format from an XML string. * [rsaKeyBits](#VB_rsaKeyBits) - Get number of significant bits in RSA key modulus. * [rsaKeyBytes](#VB_rsaKeyBytes) - Get number of bytes (octets) in RSA key modulus. * [rsaKeyValue](#VB_rsaKeyValue) - Extract a base64-encoded RSA key value from internal key string. * [rsaMakeKeys](#VB_rsaMakeKeys) - Generate an RSA public/private key pair and save as two key files. * [rsaPublicKeyFromPrivate](#VB_rsaPublicKeyFromPrivate) - Convert an internal RSA private key string into an internal public key string. * [rsaRawPrivate](#VB_rsaRawPrivate) - Carry out RSA transformation on raw data using private key. * [rsaRawPublic](#VB_rsaRawPublic) - Carry out RSA transformation on raw data using public key. * [rsaReadAnyPrivateKey](#VB_rsaReadAnyPrivateKey) - Read private key from a file or string containing a key into an "internal" public key string. * [rsaReadAnyPublicKey](#VB_rsaReadAnyPublicKey) - Read public key from a file or string containing a key into an "internal" public key string. * [rsaReadPrivateKey](#VB_rsaReadPrivateKey) - Read private key from a file or string containing a key into an "internal" public key string. * [rsaReadPublicKey](#VB_rsaReadPublicKey) - Read public key from a file or string containing a key into an "internal" public key string. * [rsaSaveEncKey](#VB_rsaSaveEncKey) - Save an internal RSA key string to an encrypted key file. * [rsaSaveKey](#VB_rsaSaveKey) - Save an internal RSA key string to a key file. * [rsaToXMLString](#VB_rsaToXMLString) - Create an XML string representation of an RSA internal key string. * [rsaToXMLStringEx](#VB_rsaToXMLStringEx) - Create an XML string representation of an RSA internal key string with option to add a namespace prefix. * [sigSignData](#VB_sigSignData) - Compute a signature value over data in a byte array. * [sigSignFile](#VB_sigSignFile) - Compute a signature value over data in a file. * [sigVerifyData](#VB_sigVerifyData) - Verify a signature value over data in a byte array. * [smimeQuery](#VB_smimeQuery) - Query an S/MIME entity for selected information. * [wipeBytes](#VB_wipeBytes) - Wipe a byte array securely. * [wipeString](#VB_wipeString) - Wipe a string securely and return an empty string. * [x509CertThumb](#VB_x509CertThumb) - Calculate the thumbprint (message digest value) of an X.509 certificate. * [x509HashIssuerAndSN](#VB_x509HashIssuerAndSN) - Calculate the message digest hash of the PKCS #7 issuerAndSerialNumber value of an X.509 certificate. * [x509QueryCert](#VB_x509QueryCert) - Query an X.509 certificate file for selected information. * [x509ReadCertStringFromP7Chain](#VB_x509ReadCertStringFromP7Chain) - Read an X.509 certificate into a base64-encoded string from PKCS-7 "certs-only" data. * [x509ReadCertStringFromPFX](#VB_x509ReadCertStringFromPFX) - Read an X.509 certificate into a base64-encoded string from PKCS-12 PFX/.p12 data. * [x509ReadStringFromFile](#VB_x509ReadStringFromFile) - Read an X.509 certificate into a base64-encoded string. * [x509TextDumpToString](#VB_x509TextDumpToString) - Dump details of an X.509 certificate or a X.509 certificate revocation list (CRL) or a PKCS-10 certificate signing request (CSR) to a string. * [xofBytes](#VB_xofBytes) - Generate bytes using an eXtendable-Output Function (XOF). ### asn1TextDumpToString Dump details of ASN.1 formatted data to a string. #### Syntax [VBA] ``` Public Function asn1TextDumpToString ( _ szFileOrPEMString As String, _ Optional nOptions As Long = 0, _ Optional szDirName As String = "" _ ) As String ``` #### Parameters szFileOrPEMString : Filename of ASN.1 formatted data file to be analyzed (or its base64 representation or PEM string). nOptions : Use 0 for default or add any of: ``` PKI_ASN1_NOCOMMENTS PKI_ASN1_ADDLEVELS ``` szDirName : Directory in which to create a temporary file. Specify `""` for default = system `TEMP` directory. #### Return Value `String:` String containing the output. #### Remarks Note different order of parameters from core function. --- ### asn1Type Describe the type of ASN.1 data. #### Syntax [VBA] ``` Public Function asn1Type ( _ szFileOrPEMString As String, _ Optional nOptions As Long = 0 _ ) As String ``` #### Parameters szFileOrPEMString : Filename of ASN.1 formatted data file to be analyzed (or a string containing its base64 or PEM representation). nOptions : For future use. #### Return Value `String:` String containing the name of the type of ASN.1 data or the empty string if not found. #### Remarks Possible return values: ``` "EC PRIVATE KEY" "OCSP REQUEST" "OCSP RESPONSE" "PKCS1 RSA PRIVATE KEY" "PKCS1 RSA PUBLIC KEY" "PKCS10 CERTIFICATE REQUEST" "PKCS12 PFX" "PKCS7 CERTIFICATE CHAIN" "PKCS7/CMS COMPRESSED DATA" "PKCS7/CMS DATA" "PKCS7/CMS ENVELOPED DATA" "PKCS7/CMS SIGNED DATA" "PKCS8 ENCRYPTED PRIVATE KEY" "PKCS8 PRIVATE KEY INFO" "PUBLIC KEY INFO" "X509 CERTIFICATE" "X509 CRL" ``` --- ### cipherDecryptAEAD Decrypt data using Authenticated Encryption with Associated Data (AEAD). The authentication tag is expected to be appended to the input ciphertext. #### Syntax [VBA] ``` Public Function cipherDecryptAEAD ( _ lpInput() As Byte, _ lpKey() As Byte, _ lpIV() As Byte, _ lpAAD() As Byte, _ nOptions As Long _ ) As Byte() ``` #### Parameters lpInput : Input data to be decrypted. lpKey : Key of exact length for algorithm (16, 24 or 32 bytes). lpIV : Initialization Vector (IV) (aka nonce) exactly 12 bytes long. lpAAD : Additional authenticated data (optional) - set as null to ignore. nOptions : Algorithm to be used. Select one from ``` PKI_AEAD_AES_128_GCM PKI_AEAD_AES_192_GCM PKI_AEAD_AES_256_GCM PKI_AEAD_CHACHA20_POLY1305 ``` Add `PKI_IV_PREFIX` to expect the IV to be prepended at the start of the input. #### Return Value `Byte():` Plaintext in a byte array, or empty array on error (an empty array may also trivially be the correct result). #### Remarks The input must include the 16-byte tag appended to the ciphertext. --- ### cipherDecryptBytes Decrypts data in a byte array using the specified block cipher algorithm, mode and padding. The key and initialization vector are passed as byte arrays. #### Syntax [VBA] ``` Public Function cipherDecryptBytes ( _ lpInput() As Byte, _ lpKey() As Byte, _ lpIV() As Byte, _ szAlgModePad As String, _ Optional nOptions As Long = 0 _ ) As Byte() ``` #### Parameters lpInput : Input data to be decrypted. lpKey : Key of exact length for block cipher algorithm. lpIV : Initialization Vector (IV) of required size (if not provided in input) or empty array for ECB mode. szAlgModePad : String with block cipher algorithm, mode and padding, e.g. `"aes128/cbc/pkcs5"` ``` Alg: aes128|aes192|aes256|tdea|3des|desede3 Mode: ecb|cbc|ofb|cfb|ctr|gcm Pad: pkcs5|nopad|oneandzeroes|ansix923|w3c ``` nOptions : Add `PKI_IV_PREFIX` to expect the IV to be prepended at the start of the input (ignored for ECB mode). #### Return Value `Byte():` Decrypted plaintext in byte array or empty array on error. #### Remarks Default padding is `Pkcs5` for ECB and CBC mode and `NoPad` for all other modes. GCM mode is only available with AES. The IV **must** be exactly 12 bytes long for GCM. --- ### cipherDecryptHex Decrypt hex-encoded data using the specified block cipher algorithm, mode and padding. The input data, key and initialization vector are all represented as hexadecimal strings. #### Syntax [VBA] ``` Public Function cipherDecryptHex ( _ szInputHex As String, _ szKeyHex As String, _ szIvHex As String, _ szAlgModePad As String, _ Optional nOptions As Long = 0 _ ) As String ``` #### Parameters szInputHex : Hex-encoded input data. szKeyHex : Hex-encoded key of exact key length. szIvHex : Hex-encoded IV of exact block length, ignored for ECB mode or if `PKI_IV_PREFIX` is used (use `""`). szAlgModePad : String with block cipher algorithm, mode and padding, e.g. `"aes128/cbc/pkcs5"` ``` Alg: aes128|aes192|aes256|tdea|3des|desede3 Mode: ecb|cbc|ofb|cfb|ctr|gcm Pad: pkcs5|nopad|oneandzeroes|ansix923|w3c ``` nOptions : Add `PKI_IV_PREFIX` to expect the IV to be prepended before the ciphertext in the input (not applicable for ECB mode). #### Return Value `String:` Decrypted plaintext in hex-encoded string or empty string on error. #### Remarks Input data may be any even number of hex characters, but not zero. Default padding is `Pkcs5` for ECB and CBC mode and `NoPad` for all other modes. GCM mode is only available with AES. The IV **must** be exactly 12 bytes long for GCM. --- ### cipherEncryptAEAD Encrypt data using Authenticated Encryption with Associated Data (AEAD). #### Syntax [VBA] ``` Public Function cipherEncryptAEAD ( _ lpInput() As Byte, _ lpKey() As Byte, _ lpIV() As Byte, _ lpAAD() As Byte, _ nOptions As Long _ ) As Byte() ``` #### Parameters lpInput : Byte array containing the input data. lpKey : Key of exact length for algorithm (16, 24 or 32 bytes). lpIV : Initialization Vector (IV) (aka nonce) exactly 12 bytes long. lpAAD : Additional authenticated data (optional) - set as empty array to ignore. nOptions : Algorithm to be used. Select one from ``` PKI_AEAD_AES_128_GCM PKI_AEAD_AES_192_GCM PKI_AEAD_AES_256_GCM PKI_AEAD_CHACHA20_POLY1305 ``` and optionally add `PKI_IV_PREFIX` to prepend the IV (nonce) before the ciphertext in the output. #### Return Value `Byte():` Ciphertext with tag appended in a byte array, or empty array on error. #### Remarks The output will either be exactly 16 bytes longer than the input, or exactly 28 bytes longer if API_IV_PREFIX is used. --- ### cipherEncryptBytes Encrypt data in a byte array using the specified block cipher algorithm, mode and padding. The key and initialization vector are passed as byte arrays. #### Syntax [VBA] ``` Public Function cipherEncryptBytes ( _ lpInput() As Byte, _ lpKey() As Byte, _ lpIV() As Byte, _ szAlgModePad As String, _ Optional nOptions As Long = 0 _ ) As Byte() ``` #### Parameters lpInput : Input data to be encrypted. lpKey : Key of exact length for block cipher algorithm. lpIV : Initialization Vector (IV) of exactly the block size, empty array for ECB mode, or 12 bytes for AES-GCM. szAlgModePad : String with block cipher algorithm, mode and padding, e.g. `"aes128/cbc/pkcs5"` ``` Alg: aes128|aes192|aes256|tdea|3des|desede3 Mode: ecb|cbc|ofb|cfb|ctr|gcm Pad: pkcs5|nopad|oneandzeroes|ansix923|w3c ``` nOptions : Add `PKI_IV_PREFIX` to prepend the IV before the ciphertext in the output (ignored for ECB mode). #### Return Value `Byte():` Ciphertext in byte array or empty array on error. #### Remarks Default padding is `Pkcs5` for ECB and CBC mode and `NoPad` for all other modes. GCM mode is only available with AES. The IV **must** be exactly 12 bytes long for GCM. --- ### cipherEncryptHex Encrypt hex-encoded data using the specified block cipher algorithm, mode and padding. The key and initialization vector are passed as hex-encoded strings. #### Syntax [VBA] ``` Public Function cipherEncryptHex ( _ szInputHex As String, _ szKeyHex As String, _ szIvHex As String, _ szAlgModePad As String, _ Optional nOptions As Long = 0 _ ) As String ``` #### Parameters szInputHex : Input data to be encrypted. szKeyHex : Hex-encoded key of exact key length. szIvHex : Hex-encoded IV of exact required length or `""` for ECB mode. szAlgModePad : String with block cipher algorithm, mode and padding, e.g. `"aes128/cbc/pkcs5"` ``` Alg: aes128|aes192|aes256|tdea|3des|desede3 Mode: ecb|cbc|ofb|cfb|ctr|gcm Pad: pkcs5|nopad|oneandzeroes|ansix923|w3c ``` nOptions : Add `PKI_IV_PREFIX` to prepend the IV before the ciphertext in the output (ignored for ECB mode). #### Return Value `String:` Encrypted ciphertext in hex-encoded string or empty string on error. #### Remarks Input data may be any even number of hex characters, but not zero. Default padding is `Pkcs5` for ECB and CBC mode and `NoPad` for all other modes. GCM mode is only available with AES. The IV **must** be exactly 12 bytes long for GCM. --- ### cipherFileDecrypt Decrypt a file. #### Syntax [VBA] ``` Public Function cipherFileDecrypt ( _ szFileOut As String, _ szFileIn As String, _ lpKey() As Byte, _ lpIV() As Byte, _ szAlgModePad As String, _ Optional nOptions As Long = 0 _ ) As Long ``` #### Parameters szFileOut : Name of output file to be created or overwritten. szFileIn : Name of input file. lpKey : Key of exact length for block cipher algorithm. lpIV : Initialization Vector (IV) of required length, or empty array for ECB mode or if IV is prefixed. szAlgModePad : String with block cipher algorithm, mode and padding, e.g. `"aes128/cbc/pkcs5"` ``` Alg: aes128|aes192|aes256|tdea|3des|desede3 Mode: ecb|cbc|ofb|cfb|ctr|gcm Pad: pkcs5|nopad|oneandzeroes|ansix923|w3c ``` nOptions : Add `PKI_IV_PREFIX` to expect the IV before the ciphertext in the input. #### Return Value `Long:` Zero on success or nonzero error code. #### Remarks `fileOut` and `fileIn` must **not** be the same. GCM mode is only available with AES. The IV **must** be exactly 12 bytes long for GCM. --- ### cipherFileEncrypt Encrypt a file. #### Syntax [VBA] ``` Public Function cipherFileEncrypt ( _ szFileOut As String, _ szFileIn As String, _ lpKey() As Byte, _ lpIV() As Byte, _ szAlgModePad As String, _ Optional nOptions As Long = 0 _ ) As Long ``` #### Parameters szFileOut : Name of output file to be created or overwritten. szFileIn : Name of input file. lpKey : Key of exact length for block cipher algorithm. lpIV : Initialization Vector (IV) of exactly the block size, empty array for ECB mode, or 12 bytes for AES-GCM. szAlgModePad : String with block cipher algorithm, mode and padding, e.g. `"aes128/cbc/pkcs5"` ``` Alg: aes128|aes192|aes256|tdea|3des|desede3 Mode: ecb|cbc|ofb|cfb|ctr|gcm Pad: pkcs5|nopad|oneandzeroes|ansix923|w3c ``` nOptions : Add `PKI_IV_PREFIX` to prepend the IV before the ciphertext in the output (ignored for ECB mode). #### Return Value `Long:` Zero on success or nonzero error code. #### Remarks `fileOut` and `fileIn` must **not** be the same. GCM mode is only available with AES. The IV **must** be exactly 12 bytes long for GCM. --- ### cipherKeyUnwrap Unwraps (decrypts) key material with a key-encryption key. #### Syntax [VBA] ``` Public Function cipherKeyUnwrap ( _ lpData() As Byte, _ lpKEK() As Byte, _ nOptions As Long _ ) As Byte() ``` #### Parameters lpData : Wrapped key. lpKEK : Key encryption key. nOptions : Algorithm to be used. Select one from: ``` PKI_BC_AES128 PKI_BC_AES192 PKI_BC_AES256 PKI_BC_3DES ``` #### Return Value `Byte():` Unwrapped key material (or empty array on error). --- ### cipherKeyWrap Wraps (encrypts) key material with a key-encryption key. #### Syntax [VBA] ``` Public Function cipherKeyWrap ( _ lpData() As Byte, _ lpKEK() As Byte, _ nOptions As Long _ ) As Byte() ``` #### Parameters lpData : Key material to be wrapped. lpKEK : Key encryption key. nOptions : Algorithm to be used. Select one from: ``` PKI_BC_AES128 PKI_BC_AES192 PKI_BC_AES256 PKI_BC_3DES ``` #### Return Value `Byte():` Wrapped key (or empty array on error). --- ### cmsGetSigDataDigest Extract the message digest from a signed-data CMS object file and verify the signature. #### Syntax [VBA] ``` Public Function cmsGetSigDataDigest ( _ szFileIn As String, _ Optional szCertFile As String = "", _ Optional nOptions As Long = 0 _ ) As String ``` #### Parameters szFileIn : Name of signed-data CMS object file or the data as a base64 or PEM string. szCertFile : An (optional) X.509 certificate file to be used to identify the signer. nOptions : For future use. #### Return Value `String:` Hash value in hex format or an empty string on error. #### Remarks If no certificate is given, it will use the first valid SignerInfo and certificate pair it finds in the SignedData. RSASSA-PKCS1V1_5 only. --- ### cmsMakeEnvData Create a CMS enveloped-data object for one or more recipients. #### Syntax [VBA] ``` Public Function cmsMakeEnvData ( _ szFileOut As String, _ szFileIn As String, _ szCertList As String, _ Optional szKeyString As String = "", _ Optional nOptions As Long = 0, _ Optional nCount As Long = 0 _ ) As Long ``` #### Parameters szFileOut : Name of output file to be created. szFileIn : Name of file containing input data. szCertList : List of one or more recipient X.509 certificate filenames, separated by semicolons (;). A certificate's representation in base64 or as a PEM string may be used instead of a filename. Alternatively, specify a single PKCS#7 certificate chain file (.p7c/.p7b). *Special cases:* Set as `"type=@pwri"` to create a single recipientInfo of the `PasswordRecipientInfo` (pwri) type; or set as `"type=@kekri,keyid="` to create a single recipientInfo of the `KEKRecipientInfo` (kekri) type. See Remarks. szKeyString : (formerly szSeed) Use to pass optional additional user key material (ukm) for KDF where KeyAgreement (kari) type or RSA-KEM is used. Or use to pass the password for a pwri type or the key encryption key (KEK) for a kekri type. Either pass a plain ASCII string, e.g. "abc" or use the format `"#x"` to pass a string of arbitrary octet values, e.g. `"#xdeadbeef01"` to pass the 5 bytes `0xde,0xad,0xbe,0xef,0x01`. Required for pwri and kekri types. nOptions : Select the content encryption algorithm from: ``` PKI_BC_AES128 (default) PKI_BC_AES192 PKI_BC_AES256 PKI_BC_3DES (legacy) PKI_AEAD_AES_128_GCM PKI_AEAD_AES_192_GCM PKI_AEAD_AES_256_GCM PKI_AEAD_CHACHA20_POLY1305 ``` To set the key transport scheme (where applicable), use one of ``` PKI_KT_RSAES_PKCS (default) PKI_KT_RSAES_OAEP PKI_KEM_RSA ``` If you have selected `PKI_KT_RSAES_OAEP` then, optionally, add ``` PKI_MGF_MGF1SHA1 ``` Select one hash algorithm where applicable: ``` PKI_HASH_SHA1 (default - CAUTION) PKI_HASH_SHA224 PKI_HASH_SHA256 PKI_HASH_SHA384 PKI_HASH_SHA512 ``` To set the key derivation function (KDF) (where applicable), add one of: ``` PKI_KDF_X963 (default for ECDH) PKI_KDF_HKDF PKI_KDF_KDF2 PKI_KDF_KDF3 (default for RSA-KEM) ``` add one key wrap algorithm for the ECDH key agreement scheme or the kekri key encryption algorithm or RSA-KEM (default=match content encryption algorithm): ``` PKI_KWRAP_3DES (legacy - allowed only if Triple DES is used for content encryption) PKI_KWRAP_AES128 PKI_KWRAP_AES192 PKI_KWRAP_AES256 ``` Optionally, add any of the bitflags: ``` PKI_CMS_FORMAT_BASE64 (default=binary) PKI_CMS_ALT_ALGID PKI_CMS_BIGFILE (binary file to binary file only) PKI_CMS_USE_SKI to use subjectKeyIdentifier (SKI) instead of issuerAndSerialNumber for RecipientInfo ``` nCount : Use to pass the iteration count for a pwri type (default=4096) or tag length for AuthEnvelopedData (in range 12-16, default=16). Otherwise ignored. #### Return Value `Long:` Number of successful recipients or a negative error code. #### Remarks The `recipientInfo` type for each recipient is set automatically depending on the public key found in their certificate. If RSA, the key transport technique (ktri) will be used; or RSA-KEM if option flag set. If ECC, then the standard ECDH ephemeral-static key agreement technique (kari) will be used. #### Example ``` ' Create an enveloped CMS object (ktri type) to Bob using Bob's RSA key... n = cmsMakeEnvData("cms2bob_aes128.p7m", "excontent.txt", "BobRSASignByCarl.cer", "", PKI_BC_AES128 Or PKI_KT_RSAES_OAEP) ' Same but using authenticated encryption and creating an authEnvelopedData object... n = cmsMakeEnvData("cms2bob_aes128auth.p7m", "excontent.txt", "BobRSASignByCarl.cer", "", PKI_AEAD_AES_128_GCM Or PKI_KT_RSAES_OAEP) ' Create an enveloped CMS object (kari type) to Dana using Dana's ECC key... n = cmsMakeEnvData("cms2dana_hkdf.p7m", "excontent.txt", "lamps-dana.encrypt.crt", "", PKI_BC_AES256 Or PKI_HASH_SHA256 Or PKI_KDF_HKDF Or PKI_KWRAP_AES256) ' Create an enveloped CMS object (kekri type) using a previously distributed symmetric key-encryption key (KEK)... n = cmsMakeEnvData("cms_envdata_kekri.p7m", "excontent.txt", "type=@kekri,keyid=ourcommonkey", "#x0123456789ABCDEFF0E1D2C3B4A59687", PKI_BC_AES256 Or PKI_HASH_SHA256 Or PKI_KWRAP_AES128) ' Create an enveloped CMS object (pwri type) using password-based key management... n = cmsMakeEnvData("cms_envdata_pwri.p7m", "excontent.txt", "type=@pwri", "password12345", PKI_BC_AES192) ``` --- ### cmsMakeEnvDataFromBytes Create a CMS enveloped-data object from data in a byte array. #### Syntax [VBA] ``` Public Function cmsMakeEnvDataFromBytes ( _ szFileOut As String, _ lpInput() As Byte, _ szCertList As String, _ Optional szKeyString As String = "", _ Optional nOptions As Long = 0, _ Optional nCount As Long = 0 _ ) As Long ``` #### Parameters szFileOut : Name of output file to be created. lpInput : Input data. szCertList : List of one or more recipient X.509 certificate filenames, separated by semicolons (;). A certificate's representation in base64 or as a PEM string may be used instead of a filename. Alternatively, specify a single PKCS#7 certificate chain file (.p7c/.p7b). *Special cases:* Set as `"type=@pwri"` to create a single recipientInfo of the `PasswordRecipientInfo` (pwri) type; or set as `"type=@kekri,keyid="` to create a single recipientInfo of the `KEKRecipientInfo` (kekri) type. See Remarks. szKeyString : (formerly szSeed) Use to pass optional additional user key material (ukm) for KDF where KeyAgreement (kari) type is used. Or use to pass the password for a pwri type or the key encryption key (KEK) for a kekri type. Either pass a plain ASCII string, e.g. "abc" or use the format `"#x"` to pass a string of arbitrary octet values, e.g. `"#xdeadbeef01"` to pass the 5 bytes `0xde,0xad,0xbe,0xef,0x01`. Required for pwri and kekri types. nOptions : See the options in [cmsMakeEnvData](#VB_cmsMakeEnvData). nCount : Use to pass the iteration count for a pwri type (default=4096) or tag length for AuthEnvelopedData (in range 12-16, default=16). Otherwise ignored. #### Return Value `Long:` Number of successful recipients or a negative error code. #### Remarks See remarks in [cmsMakeEnvData](#VB_cmsMakeEnvData) --- ### cmsMakeEnvDataFromString Create a CMS enveloped-data object from an ASCII string. #### Syntax [VBA] ``` Public Function cmsMakeEnvDataFromString ( _ szFileOut As String, _ szInput As String, _ szCertList As String, _ Optional szKeyString As String = "", _ Optional nOptions As Long = 0, _ Optional nCount As Long = 0 _ ) As Long ``` #### Parameters szFileOut : Name of output file to be created. szInput : Input data. szCertList : List of one or more recipient X.509 certificate filenames, separated by semicolons (;). A certificate's representation in base64 or as a PEM string may be used instead of a filename. Alternatively, specify a single PKCS#7 certificate chain file (.p7c/.p7b). *Special cases:* Set as `"type=@pwri"` to create a single recipientInfo of the `PasswordRecipientInfo` (pwri) type; or set as `"type=@kekri,keyid="` to create a single recipientInfo of the `KEKRecipientInfo` (kekri) type. See Remarks. szKeyString : (formerly szSeed) Use to pass optional additional user key material (ukm) for KDF where KeyAgreement (kari) type is used. Or use to pass the password for a pwri type or the key encryption key (KEK) for a kekri type. Either pass a plain ASCII string, e.g. "abc" or use the format `"#x"` to pass a string of arbitrary octet values, e.g. `"#xdeadbeef01"` to pass the 5 bytes `0xde,0xad,0xbe,0xef,0x01`. Required for pwri and kekri types. nOptions : See the options in [cmsMakeEnvData](#VB_cmsMakeEnvData). nCount : Use to pass the iteration count for a pwri type (default=4096) or tag length for AuthEnvelopedData (in range 12-16, default=16). Otherwise ignored. #### Return Value `Long:` Number of successful recipients or a negative error code. #### Remarks See remarks in [cmsMakeEnvData](#VB_cmsMakeEnvData) --- ### cmsMakeSigData Create a CMS signed-data object from an input data file. #### Syntax [VBA] ``` Public Function cmsMakeSigData ( _ szFileOut As String, _ szFileIn As String, _ szCertList As String, _ szPrivateKey As String, _ Optional nOptions As Long = 0 _ ) As Long ``` #### Parameters szFileOut : Name of output file to be created. szFileIn : Name of file containing message data to be signed. szCertList : Filename of the signer's certificate (or a string with its base64 or PEM representation) and (optionally) a list of other certificates to be included in the output, separated by semi-colons (;) Alternatively, specify a single PKCS#7 certificate chain file (.p7c/.p7b) containing the signer's certificate. szPrivateKey : Internal representation of private key for the sender. nOptions : Select the signature algorithm from one of: ``` PKI_SIG_RSA_SHA1 PKI_SIG_RSA_SHA224 PKI_SIG_RSA_SHA256 PKI_SIG_RSA_SHA384 PKI_SIG_RSA_SHA512 PKI_SIG_RSA_MD5 PKI_SIG_RSA_PSS_SHA1 PKI_SIG_RSA_PSS_SHA224 PKI_SIG_RSA_PSS_SHA256 PKI_SIG_RSA_PSS_SHA384 PKI_SIG_RSA_PSS_SHA512 PKI_SIG_ECDSA_SHA1 PKI_SIG_ECDSA_SHA224 PKI_SIG_ECDSA_SHA256 PKI_SIG_ECDSA_SHA384 PKI_SIG_ECDSA_SHA512 PKI_SIG_ED25519 PKI_SIG_ED448 ``` and optionally add any of the following: ``` PKI_CMS_EXCLUDE_CERTS PKI_CMS_EXCLUDE_DATA PKI_CMS_CERTS_ONLY PKI_CMS_USE_SKI PKI_CMS_INCLUDE_ATTRS PKI_CMS_FORMAT_BASE64 PKI_CMS_NO_OUTER PKI_CMS_ALT_ALGID PKI_CMS_BIGFILE PKI_PSS_SALTLEN_ZERO PKI_MGF_MGF1SHA1 PKI_CMS_ADD_SIGNER ``` If the `PKI_CMS_INCLUDE_ATTRS` option flag is included, optionally add any of the following: ``` PKI_CMS_ADD_SIGNTIME PKI_CMS_ADD_SMIMECAP PKI_CMS_ADD_SIGNINGCERT PKI_CMS_ADD_ALGPROTECT ``` #### Return Value `Long:` Zero on success else a nonzero error code. --- ### cmsMakeSigDataFromBytes Create a CMS signed-data object from data in a byte array. #### Syntax [VBA] ``` Public Function cmsMakeSigDataFromBytes ( _ szFileOut As String, _ lpInput() As Byte, _ szCertList As String, _ szPrivateKey As String, _ Optional nOptions As Long = 0 _ ) As Long ``` #### Parameters szFileOut : Name of output file to be created. lpInput : Input data. szCertList : Filename of the signer's certificate (or a string with its base64 or PEM representation) and (optionally) a list of other certificates to be included in the output, separated by semi-colons (;) Alternatively, specify a single PKCS#7 certificate chain file (.p7c/.p7b) containing the signer's certificate. szPrivateKey : Internal representation of private key for the sender. nOptions : Select the signature algorithm from one of: ``` PKI_SIG_RSA_SHA1 PKI_SIG_RSA_SHA224 PKI_SIG_RSA_SHA256 PKI_SIG_RSA_SHA384 PKI_SIG_RSA_SHA512 PKI_SIG_RSA_MD5 PKI_SIG_RSA_PSS_SHA1 PKI_SIG_RSA_PSS_SHA224 PKI_SIG_RSA_PSS_SHA256 PKI_SIG_RSA_PSS_SHA384 PKI_SIG_RSA_PSS_SHA512 PKI_SIG_ECDSA_SHA1 PKI_SIG_ECDSA_SHA224 PKI_SIG_ECDSA_SHA256 PKI_SIG_ECDSA_SHA384 PKI_SIG_ECDSA_SHA512 PKI_SIG_ED25519 PKI_SIG_ED448 ``` and optionally add any of the following: ``` PKI_CMS_EXCLUDE_CERTS PKI_CMS_EXCLUDE_DATA PKI_CMS_CERTS_ONLY PKI_CMS_USE_SKI PKI_CMS_INCLUDE_ATTRS PKI_CMS_FORMAT_BASE64 PKI_CMS_NO_OUTER PKI_CMS_ALT_ALGID PKI_CMS_BIGFILE PKI_PSS_SALTLEN_ZERO PKI_MGF_MGF1SHA1 PKI_CMS_ADD_SIGNER ``` If the `PKI_CMS_INCLUDE_ATTRS` option flag is included, optionally add any of the following: ``` PKI_CMS_ADD_SIGNTIME PKI_CMS_ADD_SMIMECAP PKI_CMS_ADD_SIGNINGCERT PKI_CMS_ADD_ALGPROTECT ``` #### Return Value `Long:` Zero on success else a nonzero error code. --- ### cmsMakeSigDataFromSigValue Create a CMS signed-data object using a pre-computed signature value. #### Syntax [VBA] ``` Public Function cmsMakeSigDataFromSigValue ( _ szFileOut As String, _ lpSigValue() As Byte, _ lpInput() As Byte, _ szCertList As String, _ Optional nOptions As Long = 0 _ ) As Long ``` #### Parameters szFileOut : Name of output file to be created. lpSigValue : Pre-computed signature value in byte array. lpInput : Input data. szCertList : Filename of the signer's certificate (or a string with its base64 or PEM representation) and (optionally) a list of other certificates to be included in the output, separated by semi-colons (;) Alternatively, specify a single PKCS#7 certificate chain file (.p7c/.p7b) containing the signer's certificate. nOptions : Select the signature algorithm from one of: ``` PKI_SIG_RSA_SHA1 PKI_SIG_RSA_SHA224 PKI_SIG_RSA_SHA256 PKI_SIG_RSA_SHA384 PKI_SIG_RSA_SHA512 PKI_SIG_RSA_MD5 ``` and optionally add any of the following: ``` PKI_CMS_EXCLUDE_CERTS PKI_CMS_FORMAT_BASE64 PKI_CMS_NO_OUTER PKI_CMS_ALT_ALGID PKI_CMS_PSEUDOSIG ``` #### Return Value `Long:` Zero on success else a nonzero error code. #### Remarks Specialised option for a specific case where the RSA v1.5 signature value over the content has been computed separately. RSASSA-PKCS-v1_5 only. --- ### cmsMakeSigDataFromString Create a CMS signed-data object from data in a string. #### Syntax [VBA] ``` Public Function cmsMakeSigDataFromString ( _ szFileOut As String, _ szDataIn As String, _ szCertList As String, _ szPrivateKey As String, _ Optional nOptions As Long = 0 _ ) As Long ``` #### Parameters szFileOut : Name of output file to be created. szDataIn : String containing message data to be signed. szCertList : Filename of the signer's certificate (or a string with its base64 or PEM representation) and (optionally) a list of other certificates to be included in the output, separated by semi-colons (;) Alternatively, specify a single PKCS#7 certificate chain file (.p7c/.p7b) containing the signer's certificate. szPrivateKey : Internal representation of private key for the sender. nOptions : Select the signature algorithm from one of: ``` PKI_SIG_RSA_SHA1 PKI_SIG_RSA_SHA224 PKI_SIG_RSA_SHA256 PKI_SIG_RSA_SHA384 PKI_SIG_RSA_SHA512 PKI_SIG_RSA_MD5 PKI_SIG_RSA_PSS_SHA1 PKI_SIG_RSA_PSS_SHA224 PKI_SIG_RSA_PSS_SHA256 PKI_SIG_RSA_PSS_SHA384 PKI_SIG_RSA_PSS_SHA512 PKI_SIG_ECDSA_SHA1 PKI_SIG_ECDSA_SHA224 PKI_SIG_ECDSA_SHA256 PKI_SIG_ECDSA_SHA384 PKI_SIG_ECDSA_SHA512 PKI_SIG_ED25519 PKI_SIG_ED448 ``` and optionally add any of the following: ``` PKI_CMS_EXCLUDE_CERTS PKI_CMS_EXCLUDE_DATA PKI_CMS_CERTS_ONLY PKI_CMS_USE_SKI PKI_CMS_INCLUDE_ATTRS PKI_CMS_FORMAT_BASE64 PKI_CMS_NO_OUTER PKI_CMS_ALT_ALGID PKI_CMS_BIGFILE PKI_PSS_SALTLEN_ZERO PKI_MGF_MGF1SHA1 PKI_CMS_ADD_SIGNER ``` If the `PKI_CMS_INCLUDE_ATTRS` option flag is included, optionally add any of the following: ``` PKI_CMS_ADD_SIGNTIME PKI_CMS_ADD_SMIMECAP PKI_CMS_ADD_SIGNINGCERT PKI_CMS_ADD_ALGPROTECT ``` #### Return Value `Long:` Zero on success else a nonzero error code. --- ### cmsQueryEnvData Query a CMS enveloped-data object file for selected information. #### Syntax [VBA] ``` Public Function cmsQueryEnvData ( _ szFileIn As String, _ szQuery As String, _ Optional nOptions As Long = 0 _ ) As String ``` #### Parameters szFileIn : Name of file containing CMS enveloped-data object (binary or base64-encoded) or the data as a base64 or PEM string. szQuery : Query string (case insensitive). Valid queries are: ``` "version" "recipientInfoVersion" "recipientInfoType" "CountOfRecipientInfos" "recipientIssuerName" "recipientSerialNumber" "keyEncryptionAlgorithm" "keyEncryptionFlags" "SizeofEncryptedKey" "encryptedKey" "oaepParams" "kemParams" "keyWrapAlgorithm" "originatorKeyAlgorithm" "originatorPublicKey" "keyid" "ukm" "contentEncryptionAlgorithm" "SizeofEncryptedContent" "encryptedContent" "iv" "HASsubjectKeyIndentifier" "recipientIdentifier" ``` nOptions : For future use. #### Return Value `String:` String containing the result or an empty string if not found or error. #### Remarks By default, the function queries the first recipientInfo in the file. To query the nth recipientInfo append "/n" to the query string, e.g. `"recipientInfoVersion/2"` to find the version number of the second recipientInfo in the file. --- ### cmsQuerySigData Query a CMS signed-data object file for selected information. #### Syntax [VBA] ``` Public Function cmsQuerySigData ( _ szFileIn As String, _ szQuery As String, _ Optional nOptions As Long = 0 _ ) As String ``` #### Parameters szFileIn : Name of file containing CMS signed-data object (binary or base64-encoded) or the data as a base64 or PEM string. szQuery : Query string (case insensitive). Valid queries are: ``` "version" "eContentType" "HASeContent" "CountOfCertificates" "CountOfSignerInfos" "CountOfDigestAlgs" "certificate/N" "signerInfoVersion" "digestAlgorithm" "signatureAlgorithm" "HASsignedAttributes" "signingTime" "messageDigest" "pssParams" "HASsigningCertificate" "HASalgorithmProtection" "HASsubjectKeyIndentifier" "signerIdentifier" ``` nOptions : For future use. #### Return Value `String:` String containing the result or an empty string if not found or error. #### Remarks By default, the function queries the first signerInfo in the file. To query the nth signerInfo append "/n" to the query string, e.g. `"signerInfoVersion/2"` to find the version number of the second signerInfo in the file. --- ### cmsReadEnvDataToBytes Read and decrypt a CMS enveloped-data object to a byte array. #### Syntax [VBA] ``` Public Function cmsReadEnvDataToBytes ( _ szFileIn As String, _ szCertFile As String, _ szPrivateKey As String, _ Optional nOptions As Long = 0 _ ) As Byte() ``` #### Parameters szFileIn : Name of file containing CMS enveloped-data object (binary or base64-encoded) or the data as a base64 or PEM string. szCertFile : Filename of the recipient's X.509 certificate (optional). szPrivateKey : Internal representation of private key. nOptions : For future use. #### Return Value `Byte():` Decrypted content in a byte array, or empty array on error. #### Remarks Use this if the content contains non-ASCII characters, e.g. UTF-8 encoded. --- ### cmsReadEnvDataToString Read and decrypt a CMS enveloped-data object to a string. #### Syntax [VBA] ``` Public Function cmsReadEnvDataToString ( _ szFileIn As String, _ szCertFile As String, _ szPrivateKey As String, _ Optional nOptions As Long = 0 _ ) As String ``` #### Parameters szFileIn : Name of file containing CMS enveloped-data object (binary or base64-encoded) or the data as a base64 or PEM string. szCertFile : Filename of the recipient's X.509 certificate (optional). szPrivateKey : Internal representation of private key. nOptions : For future use. #### Return Value `String:` Decrypted content in a string or empty string on error. #### Remarks Use this only when the decrypted text is known to be plain ASCII text, otherwise use `cmsReadEnvDataToBytes()`. --- ### cmsReadSigDataToBytes Read the content from a CMS signed-data object directly into a byte array. #### Syntax [VBA] ``` Public Function cmsReadSigDataToBytes ( _ szFileIn As String, _ Optional nOptions As Long = 0 _ ) As Byte() ``` #### Parameters szFileIn : Name of file containing CMS signed-data object (binary or base64-encoded) or the data as a base64 or PEM string. nOptions : For future use. #### Return Value `Byte():` Byte array containing the content or a zero-length array if error. #### Remarks Use this if the content contains non-ASCII characters, e.g. UTF-8 encoded. --- ### cmsReadSigDataToString Read the content from a CMS signed-data object directly into a string. #### Syntax [VBA] ``` Public Function cmsReadSigDataToString ( _ szFileIn As String, _ Optional nOptions As Long = 0 _ ) As String ``` #### Parameters szFileIn : Name of file containing CMS signed-data object (binary or base64-encoded) or the data as a base64 or PEM string. nOptions : For future use. #### Return Value `String:` String containing the content or an empty string on error. #### Remarks Use this only if the content is known to be plain ASCII text, otherwise use `cmsReadSigDataToBytes()`. --- ### cmsVerifySigData Verify the signature and content of a signed-data CMS object file. #### Syntax [VBA] ``` Public Function cmsVerifySigData ( _ szFileIn As String, _ Optional szCertFile As String = "", _ Optional szHexDigest As String = "", _ Optional nOptions As Long = 0 _ ) As Long ``` #### Parameters szFileIn : Name of file containing CMS signed-data object (binary or base64-encoded) or the data as a base64 or PEM string. szCertFile : (optional) X.509 certificate file of the signer. szHexDigest : (optional) digest of eContent to be verified (use for "detached-signature" form) nOptions : Add to speed up the processing of large files (binary input only). ``` PKI_CMS_BIGFILE ``` #### Return Value `Long:` Zero on success; otherwise a nonzero error code. --- ### cnvB64Filter Strip any invalid base64 characters from a string. #### Syntax [VBA] ``` Public Function cnvB64Filter ( _ szB64 As String _ ) As String ``` #### Parameters szB64 : String to be filtered. #### Return Value `String:` Filtered string. --- ### cnvB64StrFromBytes Encode an array of bytes as a base64-encoded string. #### Syntax [VBA] ``` Public Function cnvB64StrFromBytes ( _ lpData() As Byte _ ) As String ``` #### Parameters lpData : Input byte array. #### Return Value `String:` Base64-encoded string. #### Remarks Same as [cnvToBase64](#VB_cnvToBase64). --- ### cnvB64StrFromHexStr Re-encode a hexadecimal-encoded binary value as base64. #### Syntax [VBA] ``` Public Function cnvB64StrFromHexStr ( _ szHex As String _ ) As String ``` #### Parameters szHex : Hex string representing a binary value. #### Return Value `String:` Binary value encoded in base64 --- ### cnvB64StrFromString Encode an ANSI string as a base64-encoded string. #### Syntax [VBA] ``` Public Function cnvB64StrFromString ( _ szData As String _ ) As String ``` #### Parameters szData : String to be encoded. #### Return Value `String:` Base64-encoded string. #### Remarks Expecting a string of 8-bit "ANSI" characters. --- ### cnvBase58FromBytes Convert 8-bit binary data to equivalent base58-encoded string format. #### Syntax [VBA] ``` Public Function cnvBase58FromBytes ( _ lpInput() As Byte _ ) As String ``` #### Parameters lpInput : Binary data. #### Return Value `String:` Base58-encoded string. #### Remarks This uses the "Bitcoin" scheme of base58 encoding where the leading character "1" is reserved for representing an entire leading zero byte. --- ### cnvBase58ToBytes Convert a base58-encoded string to an equivalent array of 8-bit unsigned integers. #### Syntax [VBA] ``` Public Function cnvBase58ToBytes ( _ szInput As String _ ) As Byte() ``` #### Parameters szInput : Base58-encoded data. #### Return Value `Byte():` Data as array of bytes. #### Remarks This uses the "Bitcoin" scheme of base58 encoding where the leading character "1" is reserved for representing an entire leading zero byte. --- ### cnvByteEncoding Convert encoding of byte array between UTF-8 and Latin-1. #### Syntax [VBA] ``` Public Function cnvByteEncoding ( _ lpInput() As Byte, _ nOptions As Long _ ) As Byte() ``` #### Parameters lpInput : Base58-encoded data. nOptions : Option flags. Select one of: ``` PKI_CNV_UTF8_FROM_LATIN1 PKI_CNV_LATIN1_FROM_UTF8 ``` #### Return Value `Byte():` Converted data (or empty array on error). --- ### cnvBytesFromB64Str Decode a base64-encoded string as an array of Bytes. #### Syntax [VBA] ``` Public Function cnvBytesFromB64Str ( _ szB64 As String _ ) As Byte() ``` #### Parameters szB64 : Base64 data to be decoded. #### Return Value `Byte():` Binary data in byte array, or an empty array on error. #### Remarks Same as [cnvFromBase64](#VB_cnvFromBase64). --- ### cnvBytesFromHexStr Decode a hexadecimal-encoded string as an array of Bytes. #### Syntax [VBA] ``` Public Function cnvBytesFromHexStr ( _ szHex As String _ ) As Byte() ``` #### Parameters szHex : Hexadecimal data to be decoded. #### Return Value `Byte():` Binary data in byte array, or an empty array on error. #### Remarks Same as [cnvFromHex](#VB_cnvFromHex). --- ### cnvBytesLen Find length of byte array. #### Syntax [VBA] ``` Public Function cnvBytesLen ( _ ab() As Byte _ ) As Long ``` #### Parameters ab : Input byte array. #### Return Value `Long:` Number of bytes in array. #### Remarks Safe to use even if array is empty. #### Example ``` Dim ab() As Byte Debug.Print cnvBytesLen(ab) ' Expecting 0 ReDim ab(10) ' NB actually 11 elements (0..10) Debug.Print cnvBytesLen(ab) ' 11 ab = vbNullString ' Set to empty array Debug.Print cnvBytesLen(ab) ' 0 ``` --- ### cnvBytesMid Return a substring of bytes of specified length from within a given byte array #### Syntax [VBA] ``` Public Function cnvBytesMid ( _ Bytes() As Byte, _ nOffset As Long, _ Optional nBytes As Long = -1 _ ) As Byte() ``` #### Parameters Bytes : Byte array from which to return a substring (of bytes) nOffset : Offset at which substring begins. First byte is at offset zero. nBytes : Number of bytes in substring (optional). If negative, copy to end of input. #### Return Value `Byte():` A byte array containing a specified number of bytes from a byte array. --- ### cnvCheckUTF8Bytes Check if a byte array contains valid UTF-8 characters. #### Syntax [VBA] ``` Public Function cnvCheckUTF8Bytes ( _ lpInput() As Byte _ ) As Long ``` #### Parameters lpInput : data to be checked #### Return Value `Long:` Zero if the data is invalid UTF-8, or a positive number (1-3) if the input contains valid UTF-8 data. #### Remarks The return value indicates the nature of the encoded characters: ``` 0 = Not valid UTF-8 1 = Valid UTF-8, all chars are 7-bit ASCII 2 = Valid UTF-8, contains at least one multi-byte character equivalent to 8-bit ANSI 3 = Valid UTF-8, contains at least one multi-byte character that cannot be represented in a single-byte character set ``` --- ### cnvFromBase64 Decodes a base64-encoded string as an array of bytes. #### Syntax [VBA] ``` Public Function cnvFromBase64 ( _ strBase64 As String _ ) As Byte() ``` #### Parameters strBase64 : Base64 data to be decoded. #### Return Value `Byte():` Array of bytes. #### Remarks A shorter synonym for [cnvBytesFromB64Str](#VB_cnvBytesFromB64Str) --- ### cnvFromHex Decodes a hexadecimal-encoded string as an array of bytes. #### Syntax [VBA] ``` Public Function cnvFromHex ( _ strHex As String _ ) As Byte() ``` #### Parameters strHex : Hexadecimal-encoded data to be decoded. #### Return Value `Byte():` Array of bytes. #### Remarks A shorter synonym for [cnvBytesFromHexStr](#VB_cnvBytesFromHexStr) --- ### cnvHexFilter Strip any invalid hex characters from a hex string. #### Syntax [VBA] ``` Public Function cnvHexFilter ( _ szHex As String _ ) As String ``` #### Parameters szHex : String to be filtered. #### Return Value `String:` Filtered string. --- ### cnvHexFromBytesMid Encode a substring of an array of bytes as a hexadecimal-encoded string. #### Syntax [VBA] ``` Public Function cnvHexFromBytesMid ( _ abData() As Byte, _ nOffset As Long, _ nBytes As Long _ ) As String ``` #### Parameters abData : Input byte array. nOffset : Offset at which substring begins. First byte is at offset zero. nBytes : Number of bytes in substring to encode. #### Return Value `String:` Hexadecimal-encoded string. #### Example ``` Debug.Print cnvHexFromBytesMid(cnvBytesFromHexStr("00112233445566"), 3, 2) ' 3344 ``` --- ### cnvHexStrFromB64Str Re-encode a base64-encoded binary value as hexadecimal. #### Syntax [VBA] ``` Public Function cnvHexStrFromB64Str ( _ szB64 As String _ ) As String ``` #### Parameters szB64 : Base64 string representing a binary value. #### Return Value `String:` Binary value encoded in hexadecimal --- ### cnvHexStrFromBytes Encode an array of bytes as a hexadecimal-encoded string. #### Syntax [VBA] ``` Public Function cnvHexStrFromBytes ( _ lpData() As Byte _ ) As String ``` #### Parameters lpData : Input byte array. #### Return Value `String:` Hexadecimal-encoded string. #### Remarks Same as [cnvToHex](#VB_cnvToHex). --- ### cnvHexStrFromString Encode an ANSI string as a hexadecimal-encoded string. #### Syntax [VBA] ``` Public Function cnvHexStrFromString ( _ szData As String _ ) As String ``` #### Parameters szData : String to be encoded. #### Return Value `String:` Hexadecimal-encoded string. #### Remarks Expecting a string of 8-bit "ANSI" characters. --- ### cnvLatin1FromUTF8Bytes Convert UTF-8 encoded array of bytes into a Latin-1 string, if possible. #### Syntax [VBA] ``` Public Function cnvLatin1FromUTF8Bytes ( _ lpInput() As Byte _ ) As String ``` #### Parameters lpInput : Array containing UTF-8 encoded data. #### Return Value `String:` Decoded bytes in a VBA Unicode string. --- ### cnvNumFromBytes Convert the leftmost four bytes of an array to a 32-bit integer. #### Syntax [VBA] ``` Public Function cnvNumFromBytes ( _ lpInput() As Byte, _ Optional nOptions As Long = 0 _ ) As Long ``` #### Parameters lpInput : Byte array to be converted. nOptions : Option flags. Use 0 for default big-endian order or one of: ``` PKI_CNV_BIG_ENDIAN (0) PKI_CNV_LITTLE_ENDIAN ``` #### Return Value `Long:` Decoded integer value. #### Remarks An array shorter than 4 bytes will be padded on the right with zeros. #### Example ``` Debug.Print Hex(cnvNumFromBytes(cnvFromHex("DEADBEEF"))) 'DEADBEEF Debug.Print cnvNumFromBytes(cnvFromHex("DEADBEEF")) '-559038737 ``` --- ### cnvNumToBytes Convert a 32-bit integer to an array of 4 bytes. #### Syntax [VBA] ``` Public Function cnvNumToBytes ( _ nNumber As Long, _ Optional nOptions As Long = 0 _ ) As Byte() ``` #### Parameters nNumber : Integer to be converted. nOptions : Option flags. Use 0 for default big-endian order or one of: ``` PKI_CNV_BIG_ENDIAN (0) PKI_CNV_LITTLE_ENDIAN ``` #### Return Value `Byte():` Byte array containing representation of integer in given order. #### Example ``` Debug.Print cnvToHex(cnvNumToBytes(&HDEADBEEF, PKI_CNV_LITTLE_ENDIAN)) 'EFBEADDE ``` --- ### cnvReverseBytes Reverse the order of a byte array. #### Syntax [VBA] ``` Public Function cnvReverseBytes ( _ lpInput() As Byte _ ) As Byte() ``` #### Parameters lpInput : Input data to be reversed. #### Return Value `Byte():` Byte array in reverse order. #### Example ``` Debug.Print cnvToHex(cnvReverseBytes(cnvFromHex("DEADBEEF"))) 'EFBEADDE ``` --- ### cnvStringFromHexStr Decode a hexadecimal-encoded string as an ANSI string. #### Syntax [VBA] ``` Public Function cnvStringFromHexStr ( _ ByVal szHex As String _ ) As String ``` #### Parameters szHex : Hexadecimal data to be decoded. #### Return Value `String:` Decoded string. For example, "6162632E" will be converted to "abc." #### Remarks Output is a string of "ANSI" characters of value between 0 and 255. --- ### cnvToBase64 Encodes an array of bytes as a base64-encoded string. #### Syntax [VBA] ``` Public Function cnvToBase64 ( _ lpData() As Byte _ ) As String ``` #### Parameters lpData : Input byte array #### Return Value `String:` Base64-encoded string #### Remarks A shorter synonym for [cnvB64StrFromBytes](#VB_cnvB64StrFromBytes) --- ### cnvToHex Encodes an array of bytes as a hexadecimal-encoded string. #### Syntax [VBA] ``` Public Function cnvToHex ( _ lpData() As Byte _ ) As String ``` #### Parameters lpData : Input byte array #### Return Value `String:` Hexadecimal-encoded string #### Remarks A shorter synonym for [cnvHexStrFromBytes](#VB_cnvHexStrFromBytes) --- ### cnvUTF8BytesFromLatin1 Convert a string of 8-bit Latin-1 (ISO-8859-1) characters into a UTF-8 encoded array of bytes. #### Syntax [VBA] ``` Public Function cnvUTF8BytesFromLatin1 ( _ szInput As String _ ) As Byte() ``` #### Parameters szInput : String of Latin-1 characters to be converted. #### Return Value `Byte():` UTF-8 encoded sequence of bytes. --- ### comprCompress Compress data using zlib compression. #### Syntax [VBA] ``` Public Function comprCompress ( _ lpInput() As Byte, _ Optional nOptions As Long = 0 _ ) As Byte() ``` #### Parameters lpInput : Data to be compressed. nOptions : For future use. #### Return Value `Byte():` Compressed data, or an empty array on error. --- ### comprUncompress Uncompress data using zlib compression. #### Syntax [VBA] ``` Public Function comprUncompress ( _ lpInput() As Byte, _ Optional nOptions As Long = 0 _ ) As Byte() ``` #### Parameters lpInput : Data to be uncompressed. nOptions : For future use. #### Return Value `Byte():` Uncompressed data, or an empty array on error. --- ### eccDHSharedSecret Compute EC Diffie-Hellman (ECDH) shared secret. #### Syntax [VBA] ``` Public Function eccDHSharedSecret ( _ szIntPrivateKey As String, _ szIntPublicKey As String, _ Optional nOptions As Long = 0 _ ) As Byte() ``` #### Parameters szIntPrivateKey : String containing our own private key in ephemeral "internal" form. szIntPublicKey : String containing other party's public key in "internal" form. nOptions : For future use. #### Return Value `Byte():` The Diffie-Hellman shared secret, or an empty array on error. --- ### eccKeyHashCode Compute the hash code of an "internal" ECC public or private key string. #### Syntax [VBA] ``` Public Function eccKeyHashCode ( _ szIntKeyString As String _ ) As Long ``` #### Parameters szIntKeyString : Key in ephemeral "internal" representation. #### Return Value `Long:` A 32-bit hash code for the key, or zero on error. #### Remarks Should be the same for a matching private and public key. --- ### eccMakeKeys Generate an EC public/private key pair and save as two key files. #### Syntax [VBA] ``` Public Function eccMakeKeys ( _ szPubKeyFile As String, _ szPriKeyFile As String, _ szCurveName As String, _ szPassword As String, _ Optional szParams As String = "", _ Optional nOptions As Long = 0 _ ) As Long ``` #### Parameters szPubKeyFile : Output filename for public key. szPriKeyFile : Output filename for (encrypted) private key. szCurveName : Name of elliptic curve szPassword : Password for encrypted private key (required). szParams : Optional parameters. A set of attribute name=value pairs separated by a semicolon ";" (see remarks). nOptions : Use 0 for defaults. A flag to indicate the password-based encryption scheme to be used to encrypt the private key file. Select from: ``` PKI_PBE_SHA_3DES (0) for "pbeWithSHAAnd3-KeyTripleDES-CBC" from PKCS12 (default) PKI_PBE_PBKDF2_DESEDE3 for PBKDF2 using des-EDE3-CBC PKI_PBE_PBKDF2_AES128 for PBKDF2 using aes128-CBC PKI_PBE_PBKDF2_AES192 for PBKDF2 using aes192-CBC PKI_PBE_PBKDF2_AES256 for PBKDF2 using aes256-CBC ``` plus optionally to output in textual PEM format [default format=DER binary] ``` PKI_KEY_FORMAT_PEM ``` #### Return Value `Long:` Zero on success. #### Remarks Valid name-value pair parameters for `szParams` are: **count**=*integer* : To set the iteration count used in the PBKDF2 method, e.g. `"count=5000;"` [default=2048]. **prf**=*hmac-name* : To change the HMAC algorithm used in the PBKDF2 method, e.g. `"prf=hmacWithSHA256;"` [default=`hmacWithSHA1`]. **rngseed**=*string* : To add some user-supplied entropy for the key generation process, e.g. `"rngseed=pqrrr1234xyz;"`. Valid values for *hmac-name* are `{hmacWithSHA1|hmacWithSHA224|hmacWithSHA256|hmacWithSHA384|hmacWithSHA512}`. #### Example ``` ' Create an ECC key pair using defaults r = eccMakeKeys("myeccP256.pub", "myeccP256.p8e", "Secp256r1", "password") ' Same but using different curve, stronger security and in PEM format r = eccMakeKeys("myeccBP256r1.pub", "myeccBP256r1.p8e", "brainpoolP256r1", "password1", "count=6000;prf=hmacWithSHA256", PKI_PBE_PBKDF2_AES128 Or PKI_KEY_FORMAT_PEM) ``` --- ### eccPublicKeyFromPrivate Convert an internal EC private key string into an internal EC public key string. #### Syntax [VBA] ``` Public Function eccPublicKeyFromPrivate ( _ szIntKeyString As String, _ Optional nOptions As Long = 0 _ ) As String ``` #### Parameters szIntKeyString : Private key in ephemeral "internal" representation. nOptions : For future use. #### Return Value `String:` Public key in ephemeral "internal" representation, or empty string on error. --- ### eccQueryKey Query an EC key string for selected information. #### Syntax [VBA] ``` Public Function eccQueryKey ( _ szIntKeyString As String, _ szQuery As String, _ Optional nOptions As Long = 0 _ ) As String ``` #### Parameters szIntKeyString : Key in ephemeral "internal" representation. szQuery : Query string (case insensitive). Valid queries are: ``` curveName keyBits isPrivate privateKey publicKey ``` nOptions : For future use. #### Return Value `String:` String containing the result or an empty string if not found or error. --- ### eccReadKeyByCurve Read an EC key from its hexadecimal representation. #### Syntax [VBA] ``` Public Function eccReadKeyByCurve ( _ szHexKey As String, _ szCurveName As String, _ Optional nOptions As Long = 0 _ ) As String ``` #### Parameters szHexKey : Hexadecimal representation of the key, private or public. szCurveName : Name of the elliptic curve. nOptions : For **Safe Curves** specify `PKI_ECC_PRIVATE_KEY` or `PKI_ECC_PUBLIC_KEY` to indicate that the key value represents a private or public key, respectively. Otherwise, `nOptions` is ignored. #### Return Value `String:` The key in ephemeral "internal" representation, or empty string on error. --- ### eccReadPrivateKey Read an EC private key from a file into an internal key string. #### Syntax [VBA] ``` Public Function eccReadPrivateKey ( _ szKeyFileOrString As String, _ Optional szPassword As String = "", _ Optional nOptions As Long = 0 _ ) As String ``` #### Parameters szKeyFileOrString : Either the name of file containing the key or a string containing the key in PEM format. szPassword : Password for the key file, if encrypted; otherwise set as `""`. nOptions : For future use. #### Return Value `String:` String containing an internal representation of the private key, or empty string on error. --- ### eccReadPublicKey Read an EC private key from a file into an internal key string. #### Syntax [VBA] ``` Public Function eccReadPublicKey ( _ szKeyFileOrString As String, _ Optional nOptions As Long = 0 _ ) As String ``` #### Parameters szKeyFileOrString : Either the name of file containing the key or a string containing the key in PEM format. nOptions : For future use. #### Return Value `String:` String containing an internal representation of the public key, or empty string on error. --- ### eccSaveEncKey Save an internal EC private key string to an encrypted key file. #### Syntax [VBA] ``` Public Function eccSaveEncKey ( _ szOutputFile As String, _ szKeyStr As String, _ szPassword As String, _ Optional szParams As String = "", _ Optional nOptions As Long = 0 _ ) As Long ``` #### Parameters szOutputFile : Name of output file to be created. szKeyStr : The private key in an internal key string. szPassword : Password for encrypted private key (required). szParams : Optional parameters. A set of attribute name=value pairs separated by a semicolon ";" (see remarks). nOptions : Use 0 for defaults. A flag to indicate the password-based encryption scheme to be used to encrypt the private key file. Select from: ``` PKI_PBE_SHA_3DES (0) for "pbeWithSHAAnd3-KeyTripleDES-CBC" from PKCS12 (default) PKI_PBE_PBKDF2_DESEDE3 for PBKDF2 using des-EDE3-CBC PKI_PBE_PBKDF2_AES128 for PBKDF2 using aes128-CBC PKI_PBE_PBKDF2_AES192 for PBKDF2 using aes192-CBC PKI_PBE_PBKDF2_AES256 for PBKDF2 using aes256-CBC ``` plus optionally add the following to output in textual PEM format [default format=DER binary] ``` PKI_KEY_FORMAT_PEM ``` #### Return Value `Long:` Zero on success else a nonzero error code. #### Remarks Valid name-value pair parameters for `szParams` are: **count**=*integer* : To set the iteration count used in the PBKDF2 method, e.g. `"count=5000;"` [default=2048]. **prf**=*hmac-name* : To change the HMAC algorithm used in the PBKDF2 method, e.g. `"prf=hmacWithSHA256;"` [default=`hmacWithSHA1`]. Valid values for *hmac-name* are `{hmacWithSHA1|hmacWithSHA224|hmacWithSHA256|hmacWithSHA384|hmacWithSHA512}`. --- ### eccSaveKey Save an internal EC key string to a key file. #### Syntax [VBA] ``` Public Function eccSaveKey ( _ szOutputFile As String, _ szKeyStr As String, _ Optional nOptions As Long = 0 _ ) As Long ``` #### Parameters szOutputFile : Name of output file to be created. szKeyStr : Key string (public or private) in internal format. nOptions : Choose one of ``` PKI_DEFAULT (0) to save the key in the default format. PKI_KEY_TYPE_PKCS8 to save a NIST/SEC curve private key in PKCS#8 format. ``` and optionally add any of ``` PKI_KEY_FORMAT_PEM to save the key file in PEM form (default is binary DER-encoded format). PKI_KEY_LEGACY to save a safe key in "legacy" PKCS#8 v1 format (default is v2 OneAsymmetricKey). ``` #### Return Value `Long:` Zero on success else a nonzero error code. #### Remarks EC public keys are always saved in SubjectPublicKeyInfo format [RFC5480]. By default, NIST/SEC curve private keys are saved in ECPrivateKey format [RFC5915]. Use the `PKI_KEY_TYPE_PKCS8` option to save in PKCS#8 PrivateKeyInfo format [RFC5208]. Safe curve private keys (X25519, Ed25519, X448 and Ed448) are always saved in PKCS#8 v2 OneAsymmetricKey format including the public key [RFC5958]. Add the option `PKI_KEY_LEGACY` to save in older PKCS#8 v1 PrivateKeyInfo format [RFC5208] excluding the public key. To save a private key in encrypted form, use [eccSaveEncKey](#VB_eccSaveEncKey). --- ### errFormatErrorMessage Return an error message string for the last error. #### Syntax [VBA] ``` Public Function errFormatErrorMessage ( _ Optional nErrCode As Long = 0, _ Optional szMsg As String = "" _ ) As String ``` #### Parameters nErrCode : Error code returned by last function call (or zero if no code available). szMsg : Optional message to add. #### Return Value `String:` Error message as a string including previous ErrorCode, if available. #### Example ``` Debug.Print errFormatErrorMessage(11) Error (11): Parameter out of range (OUT_OF_RANGE_ERROR) Debug.Print errFormatErrorMessage(11, "User message!") ERROR: User message! (11): Value out of range (OUT_OF_RANGE_ERROR) ``` --- ### hashBytes Compute hash digest in byte format of byte input. #### Syntax [VBA] ``` Public Function hashBytes ( _ lpMessage() As Byte, _ nOptions As Long _ ) As Byte() ``` #### Parameters lpMessage : Message to be digested in byte array. nOptions : Algorithm to be used. Select one from: ``` PKI_HASH_SHA1 PKI_HASH_SHA224 PKI_HASH_SHA256 PKI_HASH_SHA384 PKI_HASH_SHA512 PKI_HASH_SHA3_224 PKI_HASH_SHA3_256 PKI_HASH_SHA3_384 PKI_HASH_SHA3_512 PKI_HASH_MD5 PKI_HASH_MD2 PKI_HASH_RMD160 PKI_HASH_BTC160 ``` and optionally add `PKI_HASH_DOUBLE` to compute a double hash, `HASH(HASH(m))`. #### Return Value `Byte():` Message digest in byte array. --- ### hashFile Compute hash digest in byte format of a file. #### Syntax [VBA] ``` Public Function hashFile ( _ szFileName As String, _ nOptions As Long _ ) As Byte() ``` #### Parameters szFileName : Name of file containing message data. nOptions : Algorithm to be used. Select one from: ``` PKI_HASH_SHA1 PKI_HASH_SHA224 PKI_HASH_SHA256 PKI_HASH_SHA384 PKI_HASH_SHA512 PKI_HASH_SHA3_224 PKI_HASH_SHA3_256 PKI_HASH_SHA3_384 PKI_HASH_SHA3_512 PKI_HASH_MD5 PKI_HASH_MD2 PKI_HASH_RMD160 PKI_HASH_BTC160 ``` and optionally add `PKI_HASH_DOUBLE` to compute a double hash, `HASH(HASH(m))`. Add `PKI_HASH_MODE_TEXT` to hash in "text" mode instead of default "binary" mode. #### Return Value `Byte():` Message digest in byte array. #### Remarks The default mode is "binary" where each byte is treated individually. In "text" mode CR-LF pairs will be treated as a single newline (LF) character. --- ### hashHexFromBytes Compute hash digest in hex format of byte input. #### Syntax [VBA] ``` Public Function hashHexFromBytes ( _ lpMessage() As Byte, _ nOptions As Long _ ) As String ``` #### Parameters lpMessage : Message to be digested in byte array. nOptions : Algorithm to be used. Select one from: ``` PKI_HASH_SHA1 PKI_HASH_SHA224 PKI_HASH_SHA256 PKI_HASH_SHA384 PKI_HASH_SHA512 PKI_HASH_SHA3_224 PKI_HASH_SHA3_256 PKI_HASH_SHA3_384 PKI_HASH_SHA3_512 PKI_HASH_MD5 PKI_HASH_MD2 PKI_HASH_RMD160 PKI_HASH_BTC160 ``` and optionally add `PKI_HASH_DOUBLE` to compute a double hash, `HASH(HASH(m))`. #### Return Value `String:` Message digest in hex-encoded format. --- ### hashHexFromFile Compute hash digest in hex format of a file. #### Syntax [VBA] ``` Public Function hashHexFromFile ( _ szFileName As String, _ nOptions As Long _ ) As String ``` #### Parameters szFileName : Name of file containing message data. nOptions : Algorithm to be used. Select one from: ``` PKI_HASH_SHA1 PKI_HASH_SHA224 PKI_HASH_SHA256 PKI_HASH_SHA384 PKI_HASH_SHA512 PKI_HASH_SHA3_224 PKI_HASH_SHA3_256 PKI_HASH_SHA3_384 PKI_HASH_SHA3_512 PKI_HASH_MD5 PKI_HASH_MD2 PKI_HASH_RMD160 PKI_HASH_BTC160 ``` and optionally add `PKI_HASH_DOUBLE` to compute a double hash, `HASH(HASH(m))`. Add `PKI_HASH_MODE_TEXT` to hash in "text" mode instead of default "binary" mode. #### Return Value `String:` Message digest in hex-encoded format. #### Remarks The default mode is "binary" where each byte is treated individually. In "text" mode CR-LF pairs will be treated as a single newline (LF) character. --- ### hashHexFromHex Compute hash digest in hex-encoded format from hex-encoded input. #### Syntax [VBA] ``` Public Function hashHexFromHex ( _ szMsgHex As String, _ nOptions As Long _ ) As String ``` #### Parameters szMsgHex : Message to be digested in hex-encoded format. nOptions : Algorithm to be used. Select one from: ``` PKI_HASH_SHA1 PKI_HASH_SHA224 PKI_HASH_SHA256 PKI_HASH_SHA384 PKI_HASH_SHA512 PKI_HASH_SHA3_224 PKI_HASH_SHA3_256 PKI_HASH_SHA3_384 PKI_HASH_SHA3_512 PKI_HASH_MD5 PKI_HASH_MD2 PKI_HASH_RMD160 PKI_HASH_BTC160 ``` and optionally add `PKI_HASH_DOUBLE` to compute a double hash, `HASH(HASH(m))`. #### Return Value `String:` Message digest in hex-encoded format. --- ### hashLength Return length of message digest output in bytes. #### Syntax [VBA] ``` Public Function hashLength ( _ nAlgId As Long _ ) As Long ``` #### Parameters nAlgId : Algorithm Id flag. Select one of `PKI_HASH_*` or `PKI_HMAC_*`, for example: ``` PKI_HASH_SHA1 PKI_HASH_SHA224 PKI_HASH_SHA256 PKI_HASH_SHA384 PKI_HASH_SHA512 PKI_HASH_SHA3_224 PKI_HASH_SHA3_256 PKI_HASH_SHA3_384 PKI_HASH_SHA3_512 PKI_HASH_MD5 PKI_HASH_MD2 PKI_HASH_RMD160 PKI_HASH_BTC160 ``` #### Return Value `Long:` Length of the hash function output in bytes; else a negative error code. #### Example ``` Debug.Print hashLength(PKI_HASH_SHA512) 64 ``` --- ### hmacBytes Compute hash-based message authentication code (HMAC) as a byte array from byte data. #### Syntax [VBA] ``` Public Function hmacBytes ( _ lpMessage() As Byte, _ lpKey() As Byte, _ nOptions As Long _ ) As Byte() ``` #### Parameters lpMessage : Message to be signed in byte format. lpKey : Key in byte format. nOptions : Algorithm to be used. Select one from: ``` PKI_HMAC_SHA1 PKI_HMAC_SHA224 PKI_HMAC_SHA256 PKI_HMAC_SHA384 PKI_HMAC_SHA512 PKI_HMAC_SHA3_224 PKI_HMAC_SHA3_256 PKI_HMAC_SHA3_384 PKI_HMAC_SHA3_512 PKI_HMAC_MD5 ``` #### Return Value `Byte():` HMAC value in byte array. --- ### hmacHexFromBytes Compute hash-based message authentication code (HMAC) in hexadecimal format from byte data. #### Syntax [VBA] ``` Public Function hmacHexFromBytes ( _ lpMessage() As Byte, _ lpKey() As Byte, _ nOptions As Long _ ) As String ``` #### Parameters lpMessage : Message to be signed in byte format. lpKey : Key in byte format. nOptions : Algorithm to be used. Select one from: ``` PKI_HMAC_SHA1 PKI_HMAC_SHA224 PKI_HMAC_SHA256 PKI_HMAC_SHA384 PKI_HMAC_SHA512 PKI_HMAC_SHA3_224 PKI_HMAC_SHA3_256 PKI_HMAC_SHA3_384 PKI_HMAC_SHA3_512 PKI_HMAC_MD5 ``` #### Return Value `String:` HMAC value in hex-encoded format. --- ### hmacHexFromHex Compute hash-based message authentication code (HMAC) in hexadecimal format from data in hexadecimal-encoded strings. #### Syntax [VBA] ``` Public Function hmacHexFromHex ( _ szMsgHex As String, _ szKeyHex As String, _ nOptions As Long _ ) As String ``` #### Parameters szMsgHex : Message to be signed in hex-encoded format. szKeyHex : Key in hex-encoded format. nOptions : Algorithm to be used. Select one from: ``` PKI_HMAC_SHA1 PKI_HMAC_SHA224 PKI_HMAC_SHA256 PKI_HMAC_SHA384 PKI_HMAC_SHA512 PKI_HMAC_SHA3_224 PKI_HMAC_SHA3_256 PKI_HMAC_SHA3_384 PKI_HMAC_SHA3_512 PKI_HMAC_MD5 ``` #### Return Value `String:` HMAC value in hex-encoded format. --- ### hpkeDerivePrivateKey Derive an EC private key in a deterministic manner from input keying material using the DeriveKeyPair algorithm in RFC9180. #### Syntax [VBA] ``` Public Function hpkeDerivePrivateKey ( _ lpIkm() As Byte, _ szCurveName As String, _ Optional nOptions As Long = 0 _ ) As String ``` #### Parameters lpIkm : Input key material (ikm). This *must* have length in bytes at least as long as the key to be produced. szCurveName : ECDH curve name. Select one from ``` "P-256" | "P-384" | "P-521" | "X25519" | "X448" ``` nOptions : Option flags. Select one of: Zero (0) to output the private key in ephemeral "internal" key format (default); or `PKI_ENCODE_HEX` to output the private key in serialized hex form. #### Return Value `String:` Derived private key in string form or an empty string on error. #### Remarks The KDF to be used is fixed by the EC curve group. By default the key is output as an ephemeral "internal" key string, which can be used directly with [eccSaveKey](#VB_eccSaveKey), [eccSaveEncKey](#VB_eccSaveEncKey), [eccPublicKeyFromPrivate](#VB_eccPublicKeyFromPrivate), [eccDHSharedSecret](#VB_eccDHSharedSecret) and [eccQueryKey](#VB_eccQueryKey). If nOptions is set to `PKI_ENCODE_HEX` then the key is output in serialized hexadecimal form in the same manner as the test vectors in [RFC9180] (without the clamping). --- ### hpkeLabeledExpand Compute the output of the LabeledExpand function as defined in RFC9180. #### Syntax [VBA] ``` Public Function hpkeLabeledExpand ( _ nBytes As Long, _ lpPrk() As Byte, _ szLabel As String, _ lpInfo() As Byte, _ szCurveName As String, _ Optional nOptions As Long = 0 _ ) As Byte() ``` #### Parameters nBytes : Required number of bytes (L) of output keying material. lpPrk : Pseudorandom key. szLabel : Label string. lpInfo : Byte string info. szCurveName : Name of ECDH curve used in scheme. Specify one of: ``` "P-256" | "P-384" | "P-521" | "X25519" | "X448" ``` nOptions : Use to specify the AEAD encryption algorithm used in the scheme (if applicable). Specify either: Zero (0) to indicate that the KDF is being used inside a KEM algorithm or, if used in the remainder of HPKE, one of: ``` PKI_AEAD_AES_128_GCM PKI_AEAD_AES_256_GCM PKI_AEAD_CHACHA20_POLY1305 ``` #### Return Value `Byte():` L bytes of output keying material. #### Remarks The ECDH curve group used in the scheme must be specified, which automatically fixes the KDF and associated HMAC algorithm to be used. --- ### hpkeLabeledExtract Compute the output of the LabeledExtract function as defined in RFC9180. #### Syntax [VBA] ``` Public Function hpkeLabeledExtract ( _ lpSalt() As Byte, _ szLabel As String, _ lpIkm() As Byte, _ szCurveName As String, _ Optional nOptions As Long = 0 _ ) As Byte() ``` #### Parameters lpSalt : Byte string salt. szLabel : Label string. lpIkm : Input keying material (ikm). szCurveName : Name of ECDH curve used in scheme. Specify one of: ``` "P-256" | "P-384" | "P-521" | "X25519" | "X448" ``` nOptions : Use to specify the AEAD encryption algorithm used in the scheme (if applicable). Specify either: Zero (0) to indicate that the KDF is being used inside a KEM algorithm or, if used in the remainder of HPKE, one of: ``` PKI_AEAD_AES_128_GCM PKI_AEAD_AES_256_GCM PKI_AEAD_CHACHA20_POLY1305 ``` #### Return Value `Byte():` A pseudorandom key of fixed length Nh bytes. #### Remarks This function outputs a fixed value of bytes equal to the length (Nh) of the underlying HMAC function used by the KDF algorithm. The ECDH curve group used in the scheme must be specified, which automatically fixes the KDF and associated HMAC algorithm to be used. --- ### kdfBytes Generate a key-encryption key (KEK) from input keying material (IKM) using a key derivation function (KDF). #### Syntax [VBA] ``` Public Function kdfBytes ( _ nKekBytes As Long, _ lpIkm() As Byte, _ lpInfo() As Byte, _ Optional nOptions As Long = 0, _ Optional szParams As String = "" _ ) As Byte() ``` #### Parameters nKekBytes : Required length of output key material in bytes. lpIkm : Input key material/shared secret. lpInfo : SharedInfo (optional, but a properly dimensioned variable must be passed, even if empty). nOptions : Algorithm to be used. Select one from: ``` PKI_KDF_X963 (default) PKI_KDF_HKDF PKI_KDF_KDF2 PKI_KDF_KDF3 ``` and select one hash algorithm to use with the key derivation function: ``` PKI_HASH_SHA1 (default) PKI_HASH_SHA224 PKI_HASH_SHA256 PKI_HASH_SHA384 PKI_HASH_SHA512 ``` szParams : Optional parameters. Set as `""` for defaults. Use `salt=` to set the optional salt parameter for the HKDF algorithm encoded in hex, e.g. `"salt=606162636465666768696a6b6c6d6e6f;"`. #### Return Value `Byte():` Output key material (KEK) in a byte array. #### Remarks `PKI_KDF_X963` uses the ANSI-X9.63-KDF key derivation function. `PKI_KDF_HKDF` uses the HMAC-based Key Derivation Function (HKDF) from RFC 5869. #### Example ``` Dim lpKEK() As Byte Dim lpZZ() As Byte Dim lpInfo() As Byte ' ansx963_2001.rsp CAVS 12.0 'ANS X9.63-2001' information for sample lpZZ = cnvFromHex("96c05619d56c328ab95fe84b18264b08725b85e33fd34f08") lpKEK = kdfBytes(128 \ 8, lpZZ, lpInfo, PKI_HASH_SHA256) Debug.Print "KEK = " & cnvToHex(lpKEK) Debug.Print "OK = 443024c3dae66b95e6f5670601558f71" ' [RFC 5869] A.1. Test Case 1 Basic test case with SHA-256 lpZZ = cnvFromHex("0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b") lpInfo = cnvFromHex("f0f1f2f3f4f5f6f7f8f9") lpKEK = kdfBytes(42, lpZZ, lpInfo, PKI_KDF_HKDF Or PKI_HASH_SHA256, "salt=000102030405060708090a0b0c") Debug.Print "KEK = " & cnvToHex(lpKEK) Debug.Print "OK = 3cb25f25faacd57a90434f64d0362f2a2d2d0a90cf1a5a4c5db02d56ecc4c5bf34007208d5b887185865" ``` --- ### kdfForCms Generate a key-encryption key (KEK) for ECDH key exchange in a CMS EnvelopedData object. #### Syntax [VBA] ``` Public Function kdfForCms ( _ lpZZ() As Byte, _ lpUkm() As Byte, _ Optional nOptions As Long = 0 _ ) As Byte() ``` #### Parameters lpZZ : Input key material/shared secret. lpUkm : User key material (optional, but a properly dimensioned variable must be passed, even if empty). nOptions : Algorithm to be used. Select one from: ``` PKI_KDF_X963 (default) PKI_KDF_HKDF ``` and select one hash algorithm to use with the key derivation function: ``` PKI_HASH_SHA1 (default) PKI_HASH_SHA224 PKI_HASH_SHA256 PKI_HASH_SHA384 PKI_HASH_SHA512 ``` and select one key wrap algorithm (required, no default): ``` PKI_KWRAP_3DES PKI_KWRAP_AES128 PKI_KWRAP_AES192 PKI_KWRAP_AES256 ``` #### Return Value `Byte():` Output key material (KEK) in a byte array. #### Remarks This is a specialist function using the key definition algorithms described in [RFC5753] and [RFC8418] when used for key agreement with ECDH in a CMS EnvelopedData object using the ECC-CMS-SharedInfo structure. #### Example ``` Dim lpKEK() As Byte Dim lpZZ() As Byte Dim lpUkm() As Byte lpZZ = cnvFromHex("160E3F5588C6FB4E9CEE8BC3C1C5000AB86396468C3D1CAEC0CB6E21536B5513") lpKEK = kdfForCms(lpZZ, lpUkm, PKI_KWRAP_AES128 Or PKI_KDF_X963 Or PKI_HASH_SHA1) Debug.Print "KEK = " & cnvToHex(lpKEK) Debug.Print "OK = 04D616C654CDF62BB186A5A088B60FB5" ``` --- ### ocspMakeRequest Create an Online Certification Status Protocol (OCSP) request as a base64 string. #### Syntax [VBA] ``` Public Function ocspMakeRequest ( _ szIssuerCert As String, _ szCertFileOrSerialNum As String, _ nOptions As Long, _ Optional szExtensions As String = "" _ ) As String ``` #### Parameters szIssuerCert : Name of issuer's X.509 certificate file (or string with its base64 representation). szCertFileOrSerialNum : Either the name of X.509 certificate file to be checked or its serial number in hexadecimal format preceded by `#x`. nOptions : Algorithm to be used. Select one from: ``` PKI_HASH_SHA1 PKI_HASH_SHA224 PKI_HASH_SHA256 PKI_HASH_SHA384 PKI_HASH_SHA512 PKI_HASH_MD5 ``` szExtensions : For future use. #### Return Value `String:` A base64 string suitable for an OCSP request to an Online Certificate Status Manager or an empty string on error. #### Remarks Note different order of parameters from core function. --- ### ocspReadResponse Read a response to an Online Certification Status Protocol (OCSP) request and outputs the main results in text form. #### Syntax [VBA] ``` Public Function ocspReadResponse ( _ szResponseFile As String, _ Optional szIssuerCert As String = "", _ Optional nOptions As Long = 0, _ Optional szExtensions As String = "" _ ) As String ``` #### Parameters szResponseFile : Name of the file containing the response data in BER format. szIssuerCert : (optional) Name of issuer's X.509 certificate file (or string with its base64 representation). nOptions : For future use. szExtensions : For future use. #### Return Value `String:` A text string outlining the main results in the response data or an empty string on error. #### Remarks Note different order of parameters from core function. --- ### padBytesBlock Creates an input block suitably padded for encryption by a block cipher in ECB or CBC mode. #### Syntax [VBA] ``` Public Function padBytesBlock ( _ lpInput() As Byte, _ nBlkLen As Long, _ Optional nOptions As Long = 0 _ ) As Byte() ``` #### Parameters lpInput : Plaintext bytes to be padded. nBlkLen : Cipher block length in bytes (8 or 16). nOptions : Use 0 for default PKCS5 padding or select one of: ``` PKI_PAD_1ZERO PKI_PAD_AX923 PKI_PAD_W3C ``` #### Return Value `Byte():` Padded data in byte array. --- ### padHexBlock Creates a hex-encoded input block suitably padded for encryption by a block cipher in ECB or CBC mode. #### Syntax [VBA] ``` Public Function padHexBlock ( _ szInput As String, _ nBlkLen As Long, _ Optional nOptions As Long = 0 _ ) As String ``` #### Parameters szInput : Hexadecimal-encoded data to be padded. nBlkLen : Cipher block length in bytes (8 or 16). nOptions : Use 0 for default PKCS5 padding or select one of: ``` PKI_PAD_1ZERO PKI_PAD_AX923 PKI_PAD_W3C ``` #### Return Value `String:` Padded data in hex-encoded string. --- ### padUnpadBytes Removes the padding from an encryption block. #### Syntax [VBA] ``` Public Function padUnpadBytes ( _ lpInput() As Byte, _ nBlkLen As Long, _ Optional nOptions As Long = 0 _ ) As Byte() ``` #### Parameters lpInput : Padded data. nBlkLen : Cipher block length in bytes (8 or 16). nOptions : Use 0 for default PKCS5 padding or select one of: ``` PKI_PAD_1ZERO PKI_PAD_AX923 PKI_PAD_W3C ``` #### Return Value `Byte():` Unpadded data in byte array or *unchanged* data on error. #### Remarks An error is indicated by returning the *original* data which will always be longer than the expected unpadded result. --- ### padUnpadHex Removes the padding from a hex-encoded encryption block. #### Syntax [VBA] ``` Public Function padUnpadHex ( _ szInput As String, _ nBlkLen As Long, _ Optional nOptions As Long = 0 _ ) As String ``` #### Parameters szInput : Hex-encoded padded data. nBlkLen : Cipher block length in bytes (8 or 16). nOptions : Use 0 for default PKCS5 padding or select one of: ``` PKI_PAD_1ZERO PKI_PAD_AX923 PKI_PAD_W3C ``` #### Return Value `String:` Unpadded data in hex-encoded string or *unchanged* data on error. #### Remarks An error is indicated by returning the *original* data which will always be longer than the expected unpadded result. --- ### pbeKdf2 Derives a key of any length from a password using the PBKDF2 algorithm from PKCS#5 v2.1. #### Syntax [VBA] ``` Public Function pbeKdf2 ( _ dkBytes As Long, _ lpPwd() As Byte, _ lpSalt() As Byte, _ nCount As Long, _ Optional nOptions As Long = 0 _ ) As Byte() ``` #### Parameters dkBytes : Required length of key in bytes. lpPwd : Password encoded as byte array. lpSalt : Salt in a byte array. nCount : Iteration count. nOptions : Hash algorithm to use in HMAC PRF. Select one from: ``` PKI_HMAC_SHA1 PKI_HMAC_SHA224 PKI_HMAC_SHA256 PKI_HMAC_SHA384 PKI_HMAC_SHA512 PKI_HMAC_MD5 ``` #### Return Value `Byte():` Key in byte array. --- ### pbeKdf2Hex Derives a hex-encoded key of any length from a password using the PBKDF2 algorithm from PKCS#5 v2.1. The salt and derived key are encoded in hexadecimal. #### Syntax [VBA] ``` Public Function pbeKdf2Hex ( _ dkBytes As Long, _ szPwd As String, _ szSaltHex As String, _ nCount As Long, _ Optional nOptions As Long = 0 _ ) As String ``` #### Parameters dkBytes : Required length of key in bytes. szPwd : Password (as normal text). szSaltHex : Salt in hex-encoded format. nCount : Iteration count. nOptions : Hash algorithm to use in HMAC PRF. Select one from: ``` PKI_HMAC_SHA1 PKI_HMAC_SHA224 PKI_HMAC_SHA256 PKI_HMAC_SHA384 PKI_HMAC_SHA512 PKI_HMAC_MD5 ``` #### Return Value `String:` Key in hex format. --- ### pbeScrypt Derives a key of any length from a password using the SCRYPT algorithm from RFC7914. #### Syntax [VBA] ``` Public Function pbeScrypt ( _ dkBytes As Long, _ lpPwd() As Byte, _ lpSalt() As Byte, _ nParamN As Long, _ nParamR As Long, _ nParamP As Long, _ Optional nOptions As Long = 0 _ ) As Byte() ``` #### Parameters dkBytes : Required length of key in bytes. lpPwd : Password encoded as byte array. lpSalt : Salt in a byte array. nParamN : CPU/Memory cost parameter `N` (`"costParameter"`), a number greater than one and a power of 2. nParamR : Block size `r` (`"blockSize"`). nParamP : Parallelization parameter `p` (`"parallelizationParameter"`). nOptions : For future use. #### Return Value `Byte():` Key in byte array. --- ### pbeScryptHex Derives a hex-encoded key of any length from a password using the SCRYPT algorithm from RFC7914. The salt and derived key are encoded in hexadecimal. #### Syntax [VBA] ``` Public Function pbeScryptHex ( _ dkBytes As Long, _ szPwd As String, _ szSaltHex As String, _ nParamN As Long, _ nParamR As Long, _ nParamP As Long, _ Optional nOptions As Long = 0 _ ) As String ``` #### Parameters dkBytes : Required length of key in bytes. szPwd : Password (as normal text). szSaltHex : Salt in hex-encoded format. nParamN : CPU/Memory cost parameter `N` (`"costParameter"`), a number greater than one and a power of 2. nParamR : Block size `r` (`"blockSize"`). nParamP : Parallelization parameter `p` (`"parallelizationParameter"`). nOptions : For future use. #### Return Value `String:` Key in hex format. #### Example ``` Debug.Print pbeScryptHex(64, "password", "4E61436C", 1024, 8, 16) ' FDBABE1C9D3472007856E7190D01E9FE7C6AD7CBC8237830E77376634B3731622EAF30D92E22A3886FF109279D9830DAC727AFB94A83EE6D8360CBDFA2CC0640 ``` --- ### pfxMakeFile Create a PFX (PKCS-12) file from an X.509 certificate and (optional) encrypted private key file. #### Syntax [VBA] ``` Public Function pfxMakeFile ( _ szFileOut As String, _ szCertList As String, _ Optional szKeyFile As String = "", _ Optional szPassword As String = "", _ Optional szFriendlyName As String = "", _ Optional nOptions As Long = 0 _ ) As Long ``` #### Parameters szFileOut : Name of output file to be created. szCertList : filename of the subject's X.509 certificate (or a string containing the certificate in base64 representation) followed by optional extra certificates to be included separated by a semicolon (;). szKeyFile : Filename of the subject's encrypted private key in pkcs-8 format (optional). szPassword : Password for private key file and new PFX file. szFriendlyName : Friendly name identification for the subject (optional). nOptions : Specialist options ``` PKI_PFX_CLONE_KEY PKI_PFX_PLAIN_CERT PKI_PFX_STRONG_CERT PKI_PFX_AES256_SHA256 PKI_PFX_DOUBLE_ENCRYPT PKI_KEY_FORMAT_PEM PKI_PFX_ALT_FORMAT ``` #### Return Value `Long:` Zero on success else a nonzero error code --- ### pkiCompileTime Get date and time the CryptoSys PKI DLL module was last compiled. #### Syntax [VBA] ``` Public Function pkiCompileTime() As String ``` #### Return Value `String:` Date and time string. --- ### pkiErrorCode Returns the error code of the error that occurred when calling the last function. #### Syntax [VBA] ``` Public Function pkiErrorCode() As Long ``` #### Return Value `Long:` Error code (see [pkiErrorLookup](#VB_pkiErrorLookup)). #### Remarks Not all functions set this value. --- ### pkiErrorLookup Get error message associated with a given error code. #### Syntax [VBA] ``` Public Function pkiErrorLookup ( _ nErrCode As Long _ ) As String ``` #### Parameters nErrCode : Error code for which the message is required. #### Return Value `String:` Error message, or empty string if no corresponding error code. --- ### pkiLastError Get last error message set by previous function. #### Syntax [VBA] ``` Public Function pkiLastError() As String ``` #### Return Value `String:` Final error message from last call (may be empty). --- ### pkiLicenceType Returns the ASCII value of the licence type. #### Syntax [VBA] ``` Public Function pkiLicenceType ( _ Optional nOptions As Long = 0 _ ) As String ``` #### Parameters nOptions : For future use. #### Return Value `String:` `D`=Developer `T`=Trial. --- ### pkiModuleInfo Get additional information about the core DLL module. #### Syntax [VBA] ``` Public Function pkiModuleInfo ( _ Optional nOptions As Long = 0 _ ) As String ``` #### Parameters nOptions : For future use. #### Return Value `String:` Additional information, e.g. "Licensed Developer Edition". --- ### pkiModuleName Get path name of the current process's module. #### Syntax [VBA] ``` Public Function pkiModuleName ( _ Optional nOptions As Long = 0 _ ) As String ``` #### Parameters nOptions : For future use. #### Return Value `String:` File path to current DLL module. #### Example ``` Debug.Print pkiModuleName() C:\WINDOWS\SYSTEM32\diCrPKI.dll ``` --- ### pkiPlatform Get platform the core DLL was compiled for. #### Syntax [VBA] ``` Public Function pkiPlatform() As String ``` #### Return Value `String:` `"Win32"` or `"X64"`. --- ### pkiVersion Get version number of native core DLL. #### Syntax [VBA] ``` Public Function pkiVersion() As Long ``` #### Return Value `Long:` Version number as an integer in form `Major*100*100 + Minor*100 + Revision`. For example, version 6.1.2 would return `60102`. --- ### prfBytes Generate output bytes using a pseudorandom function (PRF). #### Syntax [VBA] ``` Public Function prfBytes ( _ nBytes As Long, _ lpMessage() As Byte, _ lpKey() As Byte, _ nOptions As Long, _ Optional szCustom As String = "" _ ) As Byte() ``` #### Parameters nBytes : Required number of output bytes. lpMessage : Input message data. lpKey : Key (expected 128 or 256 bits long). nOptions : PRF function to be used. Select one from: ``` PKI_KMAC_128 PKI_KMAC_256 ``` szCustom : Customization string (optional). #### Return Value `Byte():` Output data in byte array. #### Remarks The KMAC128 and KMAC256 PRF functions are described in NIST SP800-185 (*SHA-3 Derived Functions*), and use SHAKE128 and SHAKE256, respectively. Note different order of parameters from core function. --- ### pwdPrompt Prompt for a password in a dialog box. #### Syntax [VBA] ``` Public Function pwdPrompt ( _ Optional szCaption As String = "", _ Optional szPrompt As String = "" _ ) As String ``` #### Parameters szCaption : Caption for the dialog box szPrompt : Wording for prompt (optional, default="Enter Password:") #### Return Value `String:` String containing password or empty string `""` if user cancels. --- ### rngBytes Generate random bytes. #### Syntax [VBA] ``` Public Function rngBytes ( _ nBytes As Long _ ) As Byte() ``` #### Parameters nBytes : Required number of random bytes. #### Return Value `Byte():` Array of random bytes. --- ### rngGuid Generate a random 36-character Global Unique IDentifier (GUID) string. #### Syntax [VBA] ``` Public Function rngGuid() As String ``` #### Return Value `String:` String of the form "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" where "x" is a hexadecimal digit [0-9a-f]. #### Example ``` Debug.Print rngGuid() ba849198-168e-4632-a865-2761c9c8dd37 ``` --- ### rngInitialize Initialize the RNG generator using a seed file. #### Syntax [VBA] ``` Public Function rngInitialize ( _ szSeedFile As String _ ) As Long ``` #### Parameters szSeedFile : Full path name of seed file. If the seed file does not exist, it will be created. #### Return Value `Long:` Zero if successful. --- ### rngInitializeEx Query and initialize the RNG generator using Intel(R) DRNG, if available. #### Syntax [VBA] ``` Public Function rngInitializeEx ( _ Optional nOptions As Long = 0 _ ) As Long ``` #### Parameters nOptions : Specify `PKI_RNG_NO_INTEL_DRNG` to explicitly turn off support. #### Return Value `Long:` Support status for Intel(R) DRNG. If available, then returns a positive value (1,2,3); else a negative error code. --- ### rsaDecodeMsg Decode an EME or EMSA encoded message block according to PKCS#1. #### Syntax [VBA] ``` Public Function rsaDecodeMsg ( _ lpInput() As Byte, _ nOptions As Long _ ) As Byte() ``` #### Parameters lpInput : Data to be decoded. nOptions : Include one of the following: ``` PKI_EME_PKCSV1_5 PKI_EME_OAEP PKI_EMSIG_PKCSV1_5 ``` If you have selected `PKI_EMSIG_PKCSV1_5`, then you can add `PKI_EMSIG_DIGINFO` to decode an 'Encoded Message for Signature' block and output the whole `DigestInfo` data instead of just the message digest. If you have selected PKI_EME_OAEP, then add one of these options to match the hash function used for EME-OAEP encoding: ``` PKI_HASH_SHA1 PKI_HASH_SHA224 PKI_HASH_SHA256 PKI_HASH_SHA384 PKI_HASH_SHA512 ``` and optionally add `PKI_MGF_MGF1SHA1` to force the MGF hash function to be SHA-1 (default = same as encoding hash function set above). Alternatively, ignore all the above and use the specialist option `PKI_EMSIG_ISO9796` to use the ISO9796-1 encoding for a signature. #### Return Value `Byte():` Decoded message. #### Remarks EME = Encoding Method for Encryption, EMSA = Encoding Method for Signature with Appendix. --- ### rsaDecrypt Decrypt a message encrypted using an RSA encryption scheme. #### Syntax [VBA] ``` Public Function rsaDecrypt ( _ lpInput() As Byte, _ szPrivateKeyFile As String, _ szPassword As String, _ nOptions As Long, _ Optional szParameters As String = "" _ ) As Byte() ``` #### Parameters lpInput : Data to be decrypted. szPrivateKeyFile : Name of the private key file, or a string containing the key in PEM format, or a valid internal private key string. szPassword : Password for encrypted private key, or `""` if password is not required. nOptions : Select one of the following: ``` PKI_EME_PKCSV1_5 (0 default) PKI_EME_OAEP ``` szParameters : For future use. #### Return Value `Byte():` Decrypted data or an empty array on error. #### Remarks Note different order of parameters from core function. --- ### rsaEncodeMsg Encode an EME or EMSA encoded message block according to PKCS#1. #### Syntax [VBA] ``` Public Function rsaEncodeMsg ( _ nBlockLen As Long, _ lpInput() As Byte, _ nOptions As Long _ ) As Byte() ``` #### Parameters nBlockLen : Length of output block in bytes (required). lpInput : Data to be encoded. nOptions : Include one of the following: ``` PKI_EME_PKCSV1_5 PKI_EME_OAEP PKI_EMSIG_PKCSV1_5 ``` If you have selected `PKI_EMSIG_PKCSV1_5`, then add one of these options to set the hash function for the signature message digest: ``` PKI_HASH_SHA1 PKI_HASH_SHA224 PKI_HASH_SHA256 PKI_HASH_SHA384 PKI_HASH_SHA512 PKI_HASH_MD5 PKI_HASH_MD2 ``` and optionally add `PKI_EMSIG_DIGESTONLY` as a flag to pass the message digest only as input to-be-signed (default = pass entire message). If you have selected PKI_EME_OAEP, then add one of these options to set the hash function used for EME-OAEP encoding: ``` PKI_HASH_SHA1 PKI_HASH_SHA224 PKI_HASH_SHA256 PKI_HASH_SHA384 PKI_HASH_SHA512 ``` and optionally add `PKI_MGF_MGF1SHA1` to force the MGF hash function to be SHA-1 (default = same as encoding hash function set above). Alternatively, ignore all the above and use the specialist option `PKI_EMSIG_ISO9796` to use the ISO9796-1 encoding for a signature. #### Return Value `Byte():` Encoded message block. #### Remarks EME = Encoding Method for Encryption, EMSA = Encoding Method for Signature with Appendix. --- ### rsaEncrypt Encrypt a short message using RSA encryption. #### Syntax [VBA] ``` Public Function rsaEncrypt ( _ lpInput() As Byte, _ szPublicKeyFile As String, _ Optional nOptions As Long = 0, _ Optional szParameters As String = "" _ ) As Byte() ``` #### Parameters lpInput : Data to be encrypted. szPublicKeyFile : Name of the public key file or X.509 certificate, or a string containing the key or certificate in PEM format, or a valid internal public key string. nOptions : Select one of the following: ``` PKI_EME_PKCSV1_5 (0 default) PKI_EME_OAEP ``` If you have selected `PKI_EME_OAEP`, then add one of these options to set the hash function for EME-OAEP encoding: ``` PKI_HASH_SHA1 PKI_HASH_SHA224 PKI_HASH_SHA256 PKI_HASH_SHA384 PKI_HASH_SHA512 ``` and, optionally, add `PKI_MGF_MGF1SHA1` to force the MGF hash function to be SHA-1 (default = same as encoding hash function set above). szParameters : For future use. #### Return Value `Byte():` Encrypted data or an empty array on error. #### Remarks Note different order of parameters from core function. --- ### rsaFromXMLString Create an RSA key string in internal format from an XML string. #### Syntax [VBA] ``` Public Function rsaFromXMLString ( _ szXmlString As String, _ Optional nOptions As Long = 0 _ ) As String ``` #### Parameters szXmlString : The RSA public or private key in XML format. nOptions : Use default zero to include the private key, if present, or add one of: `PKI_XML_EXCLPRIVATE` to exclude the private key even if present, or `PKI_XML_REQPRIVATE` to require the private key to exist in the XML input or fail. #### Return Value `String:` Key string in internal format or empty string on error. --- ### rsaKeyBits Get number of significant bits in RSA key modulus. #### Syntax [VBA] ``` Public Function rsaKeyBits ( _ szKeyString As String _ ) As Long ``` #### Parameters szKeyString : Public or private key in internal string format. #### Return Value `Long:` Number of significant bits in key. --- ### rsaKeyBytes Get number of bytes (octets) in RSA key modulus. #### Syntax [VBA] ``` Public Function rsaKeyBytes ( _ szKeyString As String _ ) As Long ``` #### Parameters szKeyString : Public or private key in internal string format. #### Return Value `Long:` Number of bytes in key. --- ### rsaKeyValue Extract a base64-encoded RSA key value from internal key string. #### Syntax [VBA] ``` Public Function rsaKeyValue ( _ szKeyString As String, _ szFieldName As String, _ Optional nOptions As Long = 0 _ ) As String ``` #### Parameters szKeyString : Public or private key in internal string format. szFieldName : Name of field to be extracted: `"Modulus"` or `"Exponent"`. nOptions : For future use. #### Return Value `String:` Value encoded in base64 or an empty string on error. --- ### rsaMakeKeys Generate an RSA public/private key pair and save as two key files. #### Syntax [VBA] ``` Public Function rsaMakeKeys ( _ szPubKeyFile As String, _ szPriKeyFile As String, _ szPassword As String, _ nBits As Long, _ Optional nExpFermat As Long = PKI_RSAEXP_EQ_65537, _ Optional szParams As String = "", _ Optional nOptions As Long = 0 _ ) As Long ``` #### Parameters szPubKeyFile : Output filename for public key. szPriKeyFile : Output filename for (encrypted) private key. szPassword : Password for encrypted private key (required). nBits : Required key modulus size in bits (min 96). nExpFermat : Exponent [default=65537=F4] szParams : Optional parameters. A set of attribute name=value pairs separated by a semicolon ";" (see remarks). nOptions : Use 0 for defaults. A flag to indicate the password-based encryption scheme to be used to encrypt the private key file. Select from: ``` PKI_PBE_SHA_3DES (0) for "pbeWithSHAAnd3-KeyTripleDES-CBC" from PKCS12 (default) PKI_PBE_PBKDF2_DESEDE3 for PBKDF2 using des-EDE3-CBC PKI_PBE_PBKDF2_AES128 for PBKDF2 using aes128-CBC PKI_PBE_PBKDF2_AES192 for PBKDF2 using aes192-CBC PKI_PBE_PBKDF2_AES256 for PBKDF2 using aes256-CBC ``` plus optionally one of the following to output in textual PEM format [default format=DER binary] ``` PKI_KEY_FORMAT_PEM PKI_KEY_FORMAT_SSL ``` and, optionally, add `PKI_KEYGEN_INDICATE` to indicate progress in a console window. #### Return Value `Long:` Zero on success. #### Remarks Valid name-value pair parameters for `szParams` are: **count**=*integer* : To set the iteration count used in the PBKDF2 method, e.g. `"count=5000;"` [default=2048]. **prf**=*hmac-name* : To change the HMAC algorithm used in the PBKDF2 method, e.g. `"prf=hmacWithSHA256;"` [default=`hmacWithSHA1`]. **rngseed**=*string* : To add some user-supplied entropy for the key generation process, e.g. `"rngseed=pqrrr1234xyz;"`. Valid values for *hmac-name* are `{hmacWithSHA1|hmacWithSHA224|hmacWithSHA256|hmacWithSHA384|hmacWithSHA512}`. #### Example ``` ' Create a 2048-bit RSA key pair using defaults r = rsaMakeKeys("myrsa2048.pub", "myrsa2048.p8e", "password", 2048) ' Same but using stronger security and in PEM format r = rsaMakeKeys("myrsa2048ex.pub", "myrsa2048ex.p8e", "password1", 2048,,"count=6000;prf=hmacWithSHA256", PKI_PBE_PBKDF2_AES128 Or PKI_KEY_FORMAT_PEM) ``` --- ### rsaPublicKeyFromPrivate Convert an internal RSA private key string into an internal public key string. #### Syntax [VBA] ``` Public Function rsaPublicKeyFromPrivate ( _ szKeyString As String, _ Optional nOptions As Long = 0 _ ) As String ``` #### Parameters szKeyString : Private key in internal string format. nOptions : For future use. #### Return Value `String:` String containing an internal representation of the public key, or an empty string on error. --- ### rsaRawPrivate Carry out RSA transformation on raw data using private key. #### Syntax [VBA] ``` Public Function rsaRawPrivate ( _ lpData() As Byte, _ szPrivateKey As String, _ Optional nOptions As Long = 0 _ ) As Byte() ``` #### Parameters lpData : Data to be transformed. szPrivateKey : Private key in internal string format. nOptions : For future use. #### Return Value `Byte():` Transformed data. #### Remarks The data **must** be same length as key modulus (use `RSA_KeyBytes()` to find this). --- ### rsaRawPublic Carry out RSA transformation on raw data using public key. #### Syntax [VBA] ``` Public Function rsaRawPublic ( _ lpData() As Byte, _ szPublicKey As String, _ Optional nOptions As Long = 0 _ ) As Byte() ``` #### Parameters lpData : Data to be transformed. szPublicKey : Public key in internal string format. nOptions : For future use. #### Return Value `Byte():` Transformed data. #### Remarks The data **must** be same length as key modulus (use `RSA_KeyBytes()` to find this). --- ### rsaReadAnyPrivateKey Read private key from a file or string containing a key into an "internal" public key string. #### Syntax [VBA] ``` Public Function rsaReadAnyPrivateKey ( _ szKeyFileOrString As String, _ Optional szPassword As String = "", _ Optional nOptions As Long = 0 _ ) As String ``` #### Parameters szKeyFileOrString : Name of file containing the key, or a string containing the key in PEM format or XML format. szPassword : Password, if the key is encrypted, or `""` if not. nOptions : For future use. #### Return Value `String:` String containing an internal representation of the private key, or an empty string on error. #### Remarks This function is the same as [rsaReadPrivateKey](#VB_rsaReadPrivateKey). --- ### rsaReadAnyPublicKey Read public key from a file or string containing a key into an "internal" public key string. #### Syntax [VBA] ``` Public Function rsaReadAnyPublicKey ( _ szKeyFileOrString As String, _ Optional nOptions As Long = 0 _ ) As String ``` #### Parameters szKeyFileOrString : Name of file containing the key, or a string containing the key in PEM format or XML format. nOptions : For future use. #### Return Value `String:` String containing an internal representation of the public key, or an empty string on error. #### Remarks This function is the same as [rsaReadPublicKey](#VB_rsaReadPublicKey). --- ### rsaReadPrivateKey Read private key from a file or string containing a key into an "internal" public key string. #### Syntax [VBA] ``` Public Function rsaReadPrivateKey ( _ szKeyFileOrString As String, _ Optional szPassword As String = "", _ Optional nOptions As Long = 0 _ ) As String ``` #### Parameters szKeyFileOrString : Name of file containing the key, or a string containing the key in PEM format or XML format. szPassword : Password, if the key is encrypted, or `""` if not. nOptions : For future use. #### Return Value `String:` String containing an internal representation of the private key, or an empty string on error. --- ### rsaReadPublicKey Read public key from a file or string containing a key into an "internal" public key string. #### Syntax [VBA] ``` Public Function rsaReadPublicKey ( _ szKeyFileOrString As String, _ Optional nOptions As Long = 0 _ ) As String ``` #### Parameters szKeyFileOrString : Name of file containing the key, or a string containing the key in PEM format or XML format. nOptions : For future use. #### Return Value `String:` String containing an internal representation of the public key, or an empty string on error. --- ### rsaSaveEncKey Save an internal RSA key string to an encrypted key file. #### Syntax [VBA] ``` Public Function rsaSaveEncKey ( _ szOutputFile As String, _ szKeyStr As String, _ szPassword As String, _ Optional szParams As String = "", _ Optional nOptions As Long = 0 _ ) As Long ``` #### Parameters szOutputFile : Name of output file to be created. szKeyStr : The private RSA key as an internal key string. szPassword : Password for encrypted private key (required). szParams : Optional parameters. A set of attribute name=value pairs separated by a semicolon ";" (see remarks). nOptions : Use 0 for defaults. A flag to indicate the password-based encryption scheme to be used to encrypt the private key file. Select from: ``` PKI_PBE_SHA_3DES (0) for "pbeWithSHAAnd3-KeyTripleDES-CBC" from PKCS12 (default) PKI_PBE_PBKDF2_DESEDE3 for PBKDF2 using des-EDE3-CBC PKI_PBE_PBKDF2_AES128 for PBKDF2 using aes128-CBC PKI_PBE_PBKDF2_AES192 for PBKDF2 using aes192-CBC PKI_PBE_PBKDF2_AES256 for PBKDF2 using aes256-CBC ``` plus optionally one of the following to output in textual PEM format [default format=DER binary] ``` PKI_KEY_FORMAT_PEM PKI_KEY_FORMAT_SSL ``` #### Return Value `Long:` Zero on success else a nonzero error code. #### Remarks Valid name-value pair parameters for `szParams` are: **count**=*integer* : To set the iteration count used in the PBKDF2 method, e.g. `"count=5000;"` [default=2048]. **prf**=*hmac-name* : To change the HMAC algorithm used in the PBKDF2 method, e.g. `"prf=hmacWithSHA256;"` [default=`hmacWithSHA1`]. Valid values for *hmac-name* are `{hmacWithSHA1|hmacWithSHA224|hmacWithSHA256|hmacWithSHA384|hmacWithSHA512}`. --- ### rsaSaveKey Save an internal RSA key string to a key file. #### Syntax [VBA] ``` Public Function rsaSaveKey ( _ szOutputFile As String, _ szKeyStr As String, _ Optional nOptions As Long = 0 _ ) As Long ``` #### Parameters szOutputFile : Name of output file to be created. szKeyStr : Key string (public or private) in internal format. nOptions : Add one of the following to output in textual PEM format [default (0) format=DER binary] ``` PKI_KEY_FORMAT_PEM PKI_KEY_FORMAT_SSL ``` #### Return Value `Long:` Zero on success else a nonzero error code. #### Remarks If the key is a private key it will be saved in *unencrypted* form. To save a private key in encrypted form, use [rsaSaveEncKey](#VB_rsaSaveEncKey). --- ### rsaToXMLString Create an XML string representation of an RSA internal key string. #### Syntax [VBA] ``` Public Function rsaToXMLString ( _ szKeyString As String, _ Optional nOptions As Long = 0 _ ) As String ``` #### Parameters szKeyString : The RSA public or private key in internal format. nOptions : Default (0) to output in appropriate W3C standard format (`RSAKeyValue` for public key and `RSAKeyPair` for private key), or select and combine: `PKI_XML_RSAKEYVALUE` to force private key output as .NET-compatible `RSAKeyValue` format (instead of W3C `RSAKeyPair`) `PKI_XML_EXCLPRIVATE` to exclude the private key (use to get a public key `RSAKeyValue` from a private key) `PKI_XML_HEXBINARY` to output with data in non-conforming (but convenient) `hexBinary` format. #### Return Value `String:` XML string or empty string on error. --- ### rsaToXMLStringEx Create an XML string representation of an RSA internal key string with option to add a namespace prefix. #### Syntax [VBA] ``` Public Function rsaToXMLStringEx ( _ szKeyString As String, _ szPrefix As String, _ Optional nOptions As Long = 0 _ ) As String ``` #### Parameters szKeyString : The RSA public or private key in internal format. szPrefix : Namespace prefix to be added to all elements, e.g. `"ds"`. nOptions : Default (0) to output in appropriate W3C standard format (`RSAKeyValue` for public key and `RSAKeyPair` for private key), or select and combine: `PKI_XML_RSAKEYVALUE` to force private key output as .NET-compatible `RSAKeyValue` format (instead of W3C `RSAKeyPair`) `PKI_XML_EXCLPRIVATE` to exclude the private key (use to get a public key `RSAKeyValue` from a private key) `PKI_XML_HEXBINARY` to output with data in non-conforming (but convenient) `hexBinary` format. #### Return Value `String:` XML string or empty string on error. #### Remarks Use this extended function to add a namespace prefix to all elements in the XML output; for example, ``. --- ### sigSignData Compute a signature value over data in a byte array. #### Syntax [VBA] ``` Public Function sigSignData ( _ lpData() As Byte, _ szKeyFile As String, _ szPassword As String, _ szAlgName As String, _ Optional nOptions As Long = 0 _ ) As String ``` #### Parameters lpData : Data to be signed. szKeyFile : name of the private key file or a string containing the key in PEM format, or a valid internal private key string. szPassword : Password for the private key, or `""` if not required. szAlgName : Signature algorithm to be used: ``` "sha1WithRSAEncryption" "sha224WithRSAEncryption" "sha256WithRSAEncryption" "sha384WithRSAEncryption" "sha512WithRSAEncryption" "md5WithRSAEncryption" "ecdsaWithSHA1" "ecdsaWithSHA224" "ecdsaWithSHA256" "ecdsaWithSHA384" "ecdsaWithSHA512" "RSA-PSS-SHA1" "RSA-PSS-SHA224" "RSA-PSS-SHA256" "RSA-PSS-SHA384" "RSA-PSS-SHA512" "Ed25519" ``` nOptions : Use 0 for defaults. Add the bitflag `PKI_SIG_USEDIGEST` to pass the digest value of the data-to-be-signed as the `lpData` argument. To change the format of the output (default base64 encoded), add one of: ``` PKI_ENCODE_BASE64URL PKI_ENCODE_HEX ``` Options for ECDSA signatures only: ``` PKI_SIG_DETERMINISTIC PKI_SIG_ASN1DER ``` Options for RSA-PSS signatures only to set the salt length (default = `hLen`): ``` PKI_PSS_SALTLEN_HLEN PKI_PSS_SALTLEN_MAX PKI_PSS_SALTLEN_20 PKI_PSS_SALTLEN_ZERO ``` and, optionally, add `PKI_MGF_MGF1SHA1` (RSA-PSS only) to force the MGF hash function to be SHA-1 (default = same as signature hash algorithm). #### Return Value `String:` The signature encoded in base64, or an empty string on error. --- ### sigSignFile Compute a signature value over data in a file. #### Syntax [VBA] ``` Public Function sigSignFile ( _ szDataFile As String, _ szKeyFile As String, _ szPassword As String, _ szAlgName As String, _ Optional nOptions As Long = 0 _ ) As String ``` #### Parameters szDataFile : Name of file to be signed. szKeyFile : name of the private key file or a string containing the key in PEM format, or a valid internal private key string. szPassword : Password for the private key, or `""` if not required. szAlgName : Signature algorithm to be used: ``` "sha1WithRSAEncryption" "sha224WithRSAEncryption" "sha256WithRSAEncryption" "sha384WithRSAEncryption" "sha512WithRSAEncryption" "md5WithRSAEncryption" "ecdsaWithSHA1" "ecdsaWithSHA224" "ecdsaWithSHA256" "ecdsaWithSHA384" "ecdsaWithSHA512" "RSA-PSS-SHA1" "RSA-PSS-SHA224" "RSA-PSS-SHA256" "RSA-PSS-SHA384" "RSA-PSS-SHA512" ``` nOptions : Use 0 for defaults. To change the format of the output (default base64 encoded), add one of: ``` PKI_ENCODE_BASE64URL PKI_ENCODE_HEX ``` Options for ECDSA signatures only: ``` PKI_SIG_DETERMINISTIC PKI_SIG_ASN1DER ``` Options for RSA-PSS signatures only to set the salt length (default = `hLen`): ``` PKI_PSS_SALTLEN_HLEN PKI_PSS_SALTLEN_MAX PKI_PSS_SALTLEN_20 PKI_PSS_SALTLEN_ZERO ``` and, optionally, add `PKI_MGF_MGF1SHA1` (RSA-PSS only) to force the MGF hash function to be SHA-1 (default = same as signature hash algorithm). #### Return Value `String:` The signature encoded in base64, or an empty string on error. #### Remarks Ed25519 is not available with this function. To sign using Ed25519, read in the file to a byte array and use [sigSignData](#VB_sigSignData). --- ### sigVerifyData Verify a signature value over data in a byte array. #### Syntax [VBA] ``` Public Function sigVerifyData ( _ szSignature As String, _ lpData() As Byte, _ szCertOrKey As String, _ szAlgName As String, _ Optional nOptions As Long = 0 _ ) As Long ``` #### Parameters szSignature : Encoded signature value lpData : Data to be verified. szCertOrKey : Name of X.509 certificate or public key file, or a string containing the certificate in base64 representation, or the public key in PEM format, or a valid internal public key string. szAlgName : Signature algorithm to be used: ``` "sha1WithRSAEncryption" "sha224WithRSAEncryption" "sha256WithRSAEncryption" "sha384WithRSAEncryption" "sha512WithRSAEncryption" "md5WithRSAEncryption" "ecdsaWithSHA1" "ecdsaWithSHA224" "ecdsaWithSHA256" "ecdsaWithSHA384" "ecdsaWithSHA512" "RSA-PSS-SHA1" "RSA-PSS-SHA224" "RSA-PSS-SHA256" "RSA-PSS-SHA384" "RSA-PSS-SHA512" "Ed25519" ``` nOptions : Use 0 for defaults. Add the bitflag `PKI_SIG_USEDIGEST` to pass the digest value of the data-to-be-signed as the `lpData` argument instead of the data itself. Add `PKI_MGF_MGF1SHA1` (RSA-PSS only) to force the MGF hash function to be SHA-1 (default = same as signature hash algorithm). #### Return Value `Long:` Zero (0) if the signature is valid; otherwise a nonzero error code. --- ### smimeQuery Query an S/MIME entity for selected information. #### Syntax [VBA] ``` Public Function smimeQuery ( _ szFileIn As String, _ szQuery As String, _ Optional nOptions As Long = 0 _ ) As String ``` #### Parameters szFileIn : Name of input file. szQuery : Query string (case insensitive). Valid queries are: ``` "content-type" "smime-type" "encoding" "name" "filename" ``` nOptions : For future use. #### Return Value `String:` String containing the result or an empty string if not found or error. #### Example ``` Debug.Print smimeQuery("cmsalice2bob-smime-env.txt", "smime-type") enveloped-data ``` --- ### wipeBytes Wipe a byte array securely. #### Syntax [VBA] ``` Public Function wipeBytes ( _ ByRef lpToWipe() As Byte _ ) As Byte() ``` #### Parameters lpToWipe : Byte array to be wiped. #### Return Value `Byte():` An empty byte array. #### Example ``` Dim lpData() As Byte lpData = cnvFromHex("DEADBEEF") Debug.Print "BEFORE: 0x(" & cnvToHex(lpData) & ")" ' BEFORE: 0x(DEADBEEF) Call wipeBytes(lpData) Debug.Print "AFTER: 0x(" & cnvToHex(lpData) & ")" ' AFTER: 0x() ``` --- ### wipeString Wipe a string securely and return an empty string. #### Syntax [VBA] ``` Public Function wipeString ( _ ByRef szToWipe As String _ ) As String ``` #### Parameters szToWipe : String to be wiped. #### Return Value `String:` An empty string. #### Remarks To use: `szToWipe = wipeString(szToWipe)` #### Example ``` Dim strData As String strData = "my deepest secrets" strData = wipeString(strData) ``` --- ### x509CertThumb Calculate the thumbprint (message digest value) of an X.509 certificate. #### Syntax [VBA] ``` Public Function x509CertThumb ( _ szCertFile As String, _ Optional nOptions As Long = 0 _ ) As String ``` #### Parameters szCertFile : Name of input file. nOptions : Algorithm to be used. Select one from: ``` PKI_HASH_SHA1 (0 = default) PKI_HASH_SHA224 PKI_HASH_SHA256 PKI_HASH_SHA384 PKI_HASH_SHA512 PKI_HASH_MD5 ``` #### Return Value `String:` Message digest in hex format or empty string on error. --- ### x509HashIssuerAndSN Calculate the message digest hash of the PKCS #7 issuerAndSerialNumber value of an X.509 certificate. #### Syntax [VBA] ``` Public Function x509HashIssuerAndSN ( _ szCertFile As String, _ Optional nOptions As Long = 0 _ ) As String ``` #### Parameters szCertFile : Name of input file. nOptions : Algorithm to be used. Select one from: ``` PKI_HASH_SHA1 (0 = default) PKI_HASH_SHA224 PKI_HASH_SHA256 PKI_HASH_SHA384 PKI_HASH_SHA512 PKI_HASH_MD5 ``` #### Return Value `String:` Message digest in hex format or empty string on error. --- ### x509QueryCert Query an X.509 certificate file for selected information. #### Syntax [VBA] ``` Public Function x509QueryCert ( _ szCertFile As String, _ szQuery As String, _ Optional nOptions As Long = 0 _ ) As String ``` #### Parameters szCertFile : Name of X.509 certificate file (or base64 representation). szQuery : Query string (case insensitive). Valid queries are: ``` "version" "serialNumber" "signatureAlgorithm" "sigAlgId" "signatureValue" "notBefore" "notAfter" "issuerName" "subjectName" "subjectPublicKeyAlgorithm" "subjectKeyIdentifier" "authorityKeyIdentifier" "rfc822Name" "isCA" "keyUsageString" "extKeyUsageString" "cRLDistributionPointsURI" "authorityInfoAccessURI" "subjectAltName" "hashAlgorithm" "pssParams" ``` nOptions : Use 0 for default or add any of: ``` PKI_X509_LATIN1 or PKI_X509_UTF8 PKI_X509_LDAP PKI_X509_DECIMAL ``` #### Return Value `String:` String containing the result or an empty string if not found or error. #### Remarks `PKI_X509_UTF8` will output attribute string encoded in UTF-8. `PKI_X509_LATIN1` will *attempt* to convert output to Latin-1 encoding. #### Example ``` Debug.Print x509QueryCert("AliceRSASignByCarl.cer", "subjectName") CN=AliceRSA ``` --- ### x509ReadCertStringFromP7Chain Read an X.509 certificate into a base64-encoded string from PKCS-7 "certs-only" data. #### Syntax [VBA] ``` Public Function x509ReadCertStringFromP7Chain ( _ szP7cFile As String, _ nIndex As Long, _ Optional nOptions As Long = 0 _ ) As String ``` #### Parameters szP7cFile : Filename of a PKCS-7 "certs-only" file, or a string containing its PEM textual representation. nIndex : Index of certificate (1,2,...) in the chain to extract. nOptions : For future use. #### Return Value `String:` String in continuous base64 format, or an empty string on error or if not found. #### Remarks Use `X509_GetCertCountInP7Chain()` to find number of certificates in the chain. --- ### x509ReadCertStringFromPFX Read an X.509 certificate into a base64-encoded string from PKCS-12 PFX/.p12 data. #### Syntax [VBA] ``` Public Function x509ReadCertStringFromPFX ( _ szPfxFile As String, _ szPassword As String, _ Optional nOptions As Long = 0 _ ) As String ``` #### Parameters szPfxFile : Filename of a PFX file, or a string containing its PEM textual representation. szPassword : Password or `""` if certificate is not encrypted. nOptions : For future use. #### Return Value `String:` String in continuous base64 format, or an empty string on error. --- ### x509ReadStringFromFile Read an X.509 certificate into a base64-encoded string. #### Syntax [VBA] ``` Public Function x509ReadStringFromFile ( _ szCertFile As String, _ Optional nOptions As Long = 0 _ ) As String ``` #### Parameters szCertFile : Name of X.509 certificate file. nOptions : For future use. #### Return Value `String:` String in continuous base64 format, or an empty string on error. --- ### x509TextDumpToString Dump details of an X.509 certificate or a X.509 certificate revocation list (CRL) or a PKCS-10 certificate signing request (CSR) to a string. #### Syntax [VBA] ``` Public Function x509TextDumpToString ( _ szCertFile As String, _ Optional nOptions As Long = 0 _ ) As String ``` #### Parameters szCertFile : Name of input file (or its base64 or PEM string representation). nOptions : Use 0 for default or add any of: ``` PKI_X509_LATIN1 PKI_X509_LDAP PKI_X509_DECIMAL ``` #### Return Value `String:` String containing the result, or an empty string on error. --- ### xofBytes Generate bytes using an eXtendable-Output Function (XOF). #### Syntax [VBA] ``` Public Function xofBytes ( _ nBytes As Long, _ lpMessage() As Byte, _ nOptions As Long _ ) As Byte() ``` #### Parameters nBytes : Required number of output bytes. lpMessage : Input message data. nOptions : XOF algorithm to be used. Select one from: ``` PKI_XOF_SHAKE128 PKI_XOF_SHAKE256 PKI_XOF_MGF1_SHA1 PKI_XOF_MGF1_SHA256 PKI_XOF_MGF1_SHA512 ``` #### Return Value `Byte():` Output data in byte array. #### Remarks The SHAKE128 and SHAKE256 XOF functions are described in NIST.FIPS.202. MGF1 is described in PKCS#1/RFC2437. --- [[Contents](#topofpage)] [[Index](#index)] C++ (STL) Functions -------------------------------------------- See [Using with C++ (STL)](#UsingWithCpp). * [dipki::Asn1::TextDump](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_asn1.html#afada981d58be3f2c270f7729f345818e "External link") - Dump details of an ASN.1 formatted data file to a text file. * [dipki::Asn1::TextDumpToString](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_asn1.html#a8a9c6f7105357424caaecac677ec056b "External link") - Dump details of ASN.1 formatted data to a string. * [dipki::Asn1::Type](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_asn1.html#abe66fd14daf02c34fa6221b8ff39c230 "External link") - Describe the type of ASN.1 data. * [dipki::Cipher::AlgName](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cipher.html#acd81730fa40163344d3742bd047af93e "External link") - Get the algorithm name. * [dipki::Cipher::BlockBytes](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cipher.html#a808966d8af3ce2610cd2d66c8049993e "External link") - Get the block size in bytes for a given cipher algorithm. * [dipki::Cipher::Decrypt](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cipher.html#aefaac2005f99930eda0875a4e97c7a49 "External link") [1/2] - Decrypt data in a byte array using the specified block cipher algorithm, mode and padding. * [dipki::Cipher::Decrypt](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cipher.html#a11632dee81df1824241acb90ea1b73e8 "External link") [2/2] - Decrypt data in a byte array using the specified block cipher algorithm, mode and padding. * [dipki::Cipher::DecryptAEAD](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cipher.html#a5c29247a4f848796ab7f832391eaa781 "External link") - Decrypt data using authenticated encryption with additional authenticated data (AAD). * [dipki::Cipher::DecryptBlock](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cipher.html#a6dd9c85f629106352b62196b30c69f50 "External link") - Decrypt a block of data. * [dipki::Cipher::Encrypt](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cipher.html#a1b78e8753a8eee4d335cc830b2337edd "External link") [1/2] - Encrypt data in a byte array using the specified block cipher algorithm, mode and padding. * [dipki::Cipher::Encrypt](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cipher.html#ae84957081fede5e2934fb68d1d60b9ba "External link") [2/2] - Encrypt data in a byte array using the specified block cipher algorithm, mode and padding. * [dipki::Cipher::EncryptAEAD](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cipher.html#abb21e6a14b2bcd15317f952eca4ab581 "External link") - Encrypt data using authenticated encryption with additional authenticated data (AAD). * [dipki::Cipher::EncryptBlock](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cipher.html#ae4a6e9b510be24d2536c8f2a1b1bd03b "External link") - Encrypt a block of data. * [dipki::Cipher::FileDecrypt](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cipher.html#ac4575aa726b28151e63bc39523aba95a "External link") - Decrypt a file. * [dipki::Cipher::FileEncrypt](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cipher.html#ae15ee22f917aca4fae21ee1c8ab2a8fd "External link") - Encrypt a file. * [dipki::Cipher::KeyBytes](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cipher.html#a02f53d053a940ceb3eb092bea5daf061 "External link") - Get the key size in bytes for a given cipher algorithm. * [dipki::Cipher::KeyUnwrap](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cipher.html#af55e7ae91b01993b1a6c02cc86c51a68 "External link") - Unwrap (decrypt) key material with a key-encryption key. * [dipki::Cipher::KeyWrap](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cipher.html#a9aebd1dab4c63244371c589d5ef5c9ba "External link") - Wrap (encrypt) key material with a key-encryption key. * [dipki::Cipher::Pad](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cipher.html#a9c5ae708169fffeb46129fa955faf200 "External link") - Pad byte array to correct length for ECB and CBC encryption. * [dipki::Cipher::Unpad](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cipher.html#a6c37c6b4d8a88785a393e019f2eab19d "External link") - Remove padding from an encryption block. * [dipki::Cms::GetSigDataDigest](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cms.html#a6ae8fc70eebf1dbc348b7df0c1273bc6 "External link") - Extract the message digest from a signed-data CMS object file. * [dipki::Cms::MakeComprData](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cms.html#a872169f6f2c0e75785c6021a23cfce63 "External link") - Create a CMS compressed-data file (.p7z) from an existing input file [binary file --> binary file]. * [dipki::Cms::MakeDetachedSig](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cms.html#a038c7a5e87adab4472215ace4b425312 "External link") - Create a "detached signature" CMS signed-data object from a message digest of the content [hexdigest --> file]. * [dipki::Cms::MakeEnvData](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cms.html#a79d88f02853eff963ad194bf98d4bcd8 "External link") [1/2] - Create a CMS enveloped-data object for one or more recipients [file --> file]. * [dipki::Cms::MakeEnvData](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cms.html#acf05de0c16ab1d1b7a0ed588f06fc20b "External link") [2/2] - Create a CMS enveloped-data object using pwri or kekri scheme [file --> file]. * [dipki::Cms::MakeEnvDataFromBytes](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cms.html#a8d245dbe1764362c0439b710e9dd344b "External link") - Create a CMS enveloped-data object for one or more recipients [bytes --> file]. * [dipki::Cms::MakeEnvDataFromString](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cms.html#a96b9276b195b0a13bde9fb2a0ecee69d "External link") - Create a CMS enveloped-data object for one or more recipients [string --> file]. * [dipki::Cms::MakeSigData](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cms.html#af25430f2abccb6b40baa9e597f619369 "External link") - Create a CMS signed-data object from a data file [file --> file]. * [dipki::Cms::MakeSigDataFromBytes](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cms.html#aafc0c8beaa5bb8e19d7242c9c6f79487 "External link") - Create a CMS signed-data object from data [bytes --> file]. * [dipki::Cms::MakeSigDataFromPseudo](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cms.html#a49dcc699222cf90dca0e47eb6e706ed5 "External link") - Create a SignedData object from a "pseudo" object. * [dipki::Cms::MakeSigDataFromSigValue](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cms.html#a5bb3e903055c1877483f9d4e912808a2 "External link") - Create a CMS object of type SignedData using a pre-computed signature value [bytes --> file]. * [dipki::Cms::MakeSigDataFromString](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cms.html#a013c817c056f71eb9e12eab5991a814d "External link") - Create a CMS signed-data object from a string [string --> file]. * [dipki::Cms::QueryEnvData](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cms.html#a8f8afaad52471d4c8d9998e20081da33 "External link") - Query a CMS enveloped-data object for selected information. * [dipki::Cms::QuerySigData](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cms.html#ae57ff9120187189f447b47fce29aa05c "External link") - Query a CMS signed-data object for selected information. * [dipki::Cms::ReadComprData](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cms.html#af369d8fd68584480f57befcd10117261 "External link") - Read and extract the decompressed contents of a CMS compressed-data file [binary file --> binary file]. * [dipki::Cms::ReadEnvDataToBytes](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cms.html#adf858b4035b5091bbd9cdf6161f364f3 "External link") - Read and decrypt a CMS enveloped-data object to a byte array [file --> bytes]. * [dipki::Cms::ReadEnvDataToFile](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cms.html#afad6be6e9ab0199d8a8a4143f731f6f6 "External link") - Read and decrypt a CMS enveloped-data object to a file [file --> file]. * [dipki::Cms::ReadSigDataToBytes](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cms.html#a195dd3ffebf14da82afbcb38c0d3ee70 "External link") - Read and decrypt a CMS enveloped-data object to a byte array [file --> bytes]. * [dipki::Cms::ReadSigDataToFile](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cms.html#a7bd1e326ed04aac001b35514bc1e1a89 "External link") - Read the content from a CMS signed-data object file [file --> file]. * [dipki::Cms::VerifySigData](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cms.html#a716d8daac452731ba32ebf01616f02d9 "External link") - Verify the signature and content of a signed-data CMS object file. * [dipki::Cnv::CheckUTF8](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cnv.html#a03053e41be4471efaacc4c178671e92d "External link") - Check that a byte array contains only valid UTF-8 encoded characters. * [dipki::Cnv::CheckUTF8CodeAsString](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cnv.html#aee5aa359ca1c5aa048828f3ac0782421 "External link") - Return a string describing an integer code returned by Cnv::CheckUTF8 or Cnv::CheckUTF8File. * [dipki::Cnv::CheckUTF8File](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cnv.html#acdd517ccb3e1c1c367e2425c1571420a "External link") - Check that a file contains only valid UTF-8 encoded characters. * [dipki::Cnv::FromBase58](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cnv.html#a1eb3f31614c1aa5286af0c7823f7f8db "External link") - Decodes a base58-encoded string as an array of bytes. * [dipki::Cnv::FromBase64](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cnv.html#af74aa67af858aea47407c4e55fd23e97 "External link") - Decodes a base64-encoded string as an array of bytes. * [dipki::Cnv::FromHex](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cnv.html#ae5758db60d6e736aa7f02d9897d88d25 "External link") - Decodes a hexadecimal-encoded string as an array of bytes. * [dipki::Cnv::Latin1FromUTF8Bytes](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cnv.html#a53aff21e51cfd1b4b496d61d1cf8959a "External link") - Converts UTF-8 encoded array of bytes into a Latin-1 string, if possible. * [dipki::Cnv::NumFromBytes](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cnv.html#a258627606677910096c29c970efb3110 "External link") - Convert the leftmost four bytes of an array to an unsigned 32-bit integer. * [dipki::Cnv::NumToBytes](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cnv.html#a981d66f0e73e13f80707c841fe62c3a2 "External link") - Convert a 32-bit integer to an array of 4 bytes. * [dipki::Cnv::ReverseBytes](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cnv.html#a6ae41201c7f200770c2f1d3c4516fb67 "External link") - Reverse the order of a byte array. * [dipki::Cnv::ShortPathName](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cnv.html#a8d38d8d0febbd2e163e07766ce50921a "External link") - Retrieve the Windows short path form of the specified path. * [dipki::Cnv::ToBase58](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cnv.html#af09afd9cc0eacd54cbc66b9ea0ff1c43 "External link") - Encodes an array of bytes as a base58-encoded string. * [dipki::Cnv::ToBase64](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cnv.html#a53fa6ab77bbb5623e134f72199a407d6 "External link") [1/2] - Encodes an array of bytes as a base64-encoded string. * [dipki::Cnv::ToBase64](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cnv.html#a8e32a430afe218683b5f63f64b08e641 "External link") [2/2] - Encodes a string as a base64-encoded string. * [dipki::Cnv::ToHex](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cnv.html#a5810eaae94a26966d7b0f3f38d020b53 "External link") [1/2] - Encodes an array of bytes as a hexadecimal-encoded string. * [dipki::Cnv::ToHex](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cnv.html#ab8105e17761c59fbd94dada6e4ad553b "External link") [2/2] - Encodes a string as a hexadecimal-encoded string. * [dipki::Cnv::UTF8BytesFromLatin1](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cnv.html#ab68bc113efd373567ab51914ee0f88d3 "External link") - Converts a string of 8-bit Latin-1 characters into a UTF-8 encoded array of bytes. * [dipki::Cnv::Utf8FromWide](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_cnv.html#a9ede836655f91e2caa3288720d6c08fa "External link") - Map a UTF-16 (wide character) string to a UTF-8-encoded string. * [dipki::Compr::Compress](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_compr.html#adb335ad3ad155607aae0211338a9b699 "External link") - Compress data using zlib compression. * [dipki::Compr::Uncompress](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_compr.html#a24cae59498eff5ebf00d075cb1dc7b02 "External link") - Uncompress data using zlib compression. * [dipki::Ecc::CurveNameAsString](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_ecc.html#addd566d05538f74acb0dba09786f8632 "External link") - Get curve name as a string. * [dipki::Ecc::DHSharedSecret](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_ecc.html#a641375295d539a47a74f1415cc62b126 "External link") - Compute EC Diffie-Hellman (ECDH) shared secret. * [dipki::Ecc::KeyHashCode](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_ecc.html#ab038341ad84051f76c27a4961b899603 "External link") - Compute the hash code of an "internal" ECC public or private key string. * [dipki::Ecc::MakeKeys](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_ecc.html#a61c359b0da5243cb7e028d0a2e7cce08 "External link") - Generate an EC public/private key pair and save as two key files. * [dipki::Ecc::PublicKeyFromPrivate](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_ecc.html#a71a6adfb1db7101969d7b625b9d8d842 "External link") - Convert an internal EC private key string into an internal EC public key string. * [dipki::Ecc::QueryKey](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_ecc.html#abe2d746ed26a73dc4404f59b96df7fd6 "External link") - Query an EC key string for selected information. * [dipki::Ecc::ReadKeyByCurve](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_ecc.html#a9201fbe6d4b6b5a45c47b3865253ce7e "External link") - Read an EC key from its hexadecimal representation. * [dipki::Ecc::ReadPrivateKey](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_ecc.html#a7ab4058c743e56c7e14ecd7812cd8173 "External link") - Read from a file or a string containing an EC private key into an "internal" private key string. * [dipki::Ecc::ReadPublicKey](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_ecc.html#af296521d6be949c86bb388db37750c99 "External link") - Read from a file or a string containing an EC public key into an "internal" public key string. * [dipki::Ecc::SaveEncKey](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_ecc.html#a069ed15422bafa4f727e6219de02ef64 "External link") - Save an internal EC private key string to an encrypted private key file. * [dipki::Ecc::SaveKey](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_ecc.html#a555d6cf01c2630f0e225198723b9518b "External link") - Save an internal EC key string (public or private) to an unencrypted key file. * [dipki::Err::ErrorLookup](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_err.html#ad218a5ca4591b58f1b0cf2a1a853f402 "External link") - Look up description for error code. * [dipki::Err::FormatErrorMessage](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_err.html#a27fe49e87703af2c7935028497bbadde "External link") - Return an error message string for the last error. * [dipki::Err::LastError](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_err.html#a8df1f51e1ffacd29e58a610c0a5ae58d "External link") - Retrieve the last error message (if available). * [dipki::Gen::CompileTime](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_gen.html#a732f1c215c41715dae749f05ef1e5e7c "External link") - Get date and time the core native DLL module was last compiled. * [dipki::Gen::LicenceType](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_gen.html#a740d056f996720c32bb48d6c9a80883a "External link") - Get licence type as a string. * [dipki::Gen::ModuleInfo](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_gen.html#a131219a3f8ad6f704d9b34dcfd041088 "External link") - Get information about the core module. * [dipki::Gen::ModuleName](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_gen.html#a1dab5a1f9481bc2e9d03b241707c8b41 "External link") - Get full path name of the current process's core native DLL. * [dipki::Gen::Platform](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_gen.html#af2e8acdc25d91b79ba5603088108f984 "External link") - Get platform the core native DLL was compiled for. * [dipki::Gen::Version](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_gen.html#a5274e15a8183189f52b300e807037756 "External link") - Get version number of the core native DLL as an integer value. * [dipki::Hash::AlgName](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_hash.html#ae18e18be1d74c32bc18819e991cba14e "External link") - Get the algorithm name. * [dipki::Hash::Bytes](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_hash.html#ad7b2346b1e672cda85f4685feeb4e851 "External link") - Compute hash digest over byte array. * [dipki::Hash::Double](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_hash.html#a91567bb5268d8410b8709e7cf37da0d2 "External link") - Create double hash (hash of hash). * [dipki::Hash::File](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_hash.html#a02207143699c3b81a57b54ffc8bc1729 "External link") - Compute hash digest over a binary file. * [dipki::Hash::HashAlgFromString](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_hash.html#a50c19afc2443b66393786d2f0a124cf5 "External link") - Get hash algorithm from a string. * [dipki::Hash::HexFromBytes](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_hash.html#ad21a696ec3eadb80d1f362c5ad7fc0f8 "External link") - Compute hash digest in hex format over byte array. * [dipki::Hash::HexFromFile](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_hash.html#a20201d2aa3e4eb8372616ff1d3a0361c "External link") - Compute hash digest in hex format over a file. * [dipki::Hash::HexFromHex](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_hash.html#a32622d3a194234770744e300db0215f0 "External link") - Compute hash digest in hex format over hex-encoded input. * [dipki::Hash::HexFromString](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_hash.html#aac1ec55a49cad50c09a8cc2ff7efcd6b "External link") - Compute hash digest in hex format over string input. * [dipki::Hash::Length](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_hash.html#a14f9dc55c1f84a66f7729b64e70dd740 "External link") - Return length of message digest output in bytes. * [dipki::Hmac::Bytes](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_hmac.html#ae6e138b6d6c13d03e2dbd2953a03c902 "External link") - Compute HMAC over byte array. * [dipki::Hmac::HexFromBytes](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_hmac.html#a42d50f89e1642e1256c499bfb3c93863 "External link") - Compute HMAC in hex format over byte array. * [dipki::Hmac::HexFromHex](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_hmac.html#aedb10f9b3b1e3c29b10c39a4534fb60a "External link") - Compute HMAC in hex format over hex-encoded input. * [dipki::Hmac::HexFromString](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_hmac.html#ac3bf0896a57165b5be3a319aa4095f02 "External link") - Compute HMAC in hex format over string input. * [dipki::Hpke::DerivePrivateKey](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_hpke.html#a5897999f600ef45d4c8da7217d712c5e "External link") - Derive an EC private key in a deterministic manner from input keying material using the DeriveKeyPair algorithm in RFC9180. * [dipki::Hpke::LabeledExpand](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_hpke.html#a2fc65341143e165391f69aebf5950541 "External link") - Compute the output of the LabeledExpand function as defined in RFC9180. * [dipki::Hpke::LabeledExtract](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_hpke.html#a27d47d152488346f40b650cdf6063b88 "External link") - Compute the output of the LabeledExtract function as defined in RFC9180. * [dipki::Kdf::Bytes](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_kdf.html#ad3196c7ce3cf9588c27782d2c1e7ede9 "External link") - Generate a key-encryption key (KEK) from input keying material (IKM) using a key derivation function (KDF). * [dipki::Kdf::ForCms](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_kdf.html#a646a8ea8e026b47e4177950ccfe2159a "External link") - Generate a key-encryption key (KEK) for ECDH key exchange in a CMS EnvelopedData object. * [dipki::Ocsp::MakeRequest](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_ocsp.html#af639efb0c08004ee072481faa28393ac "External link") - Create an Online Certification Status Protocol (OCSP) request as a base64 string. * [dipki::Ocsp::ReadResponse](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_ocsp.html#a0e078b975897cfd0433904c61959dc76 "External link") - Read a response to an Online Certification Status Protocol (OCSP) request and outputs the main results in text form. * [dipki::Pbe::Kdf2](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_pbe.html#a1ad12199140373ac7a6dbbf4a936ce65 "External link") - Derive a key of any length from a password using the PBKDF2 algorithm from PKCS #5 v2.1. * [dipki::Pbe::Scrypt](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_pbe.html#a802fc639667ab1999be8e1c19cf16cd1 "External link") - Derive a key of any length from a password using the SCRYPT algorithm from RFC7914. * [dipki::Pem::FileFromBinFile](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_pem.html#a94dbda8a7c4e2bf2292329e83fe245dc "External link") - Create a PEM file from a binary file. * [dipki::Pem::FileToBinFile](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_pem.html#a5c1beb5fe93e5e1ede340216f283f04d "External link") - Convert the contents of a PEM file into a binary file. * [dipki::Pfx::MakeFile](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_pfx.html#a7a42e6bb9df32c43243b0d6910bded9b "External link") - Create a PFX (PKCS-12) file from an X.509 certificate and (optional) encrypted private key file. * [dipki::Pfx::SignatureIsValid](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_pfx.html#a26bbea62dceae2f6994049f79a7e8706 "External link") - Verify the MacData signature in a PKCS-12 file. * [dipki::Prf::Bytes](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_prf.html#ad1500746341457d180a3b9ba73424030 "External link") - Generate output bytes using a pseudorandom function (PRF). * [dipki::Pwd::Prompt](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_pwd.html#ac74618d08be72b6f619310ab30a6e03b "External link") - Open a dialog box to receive a password with user-supplied prompt. * [dipki::Rng::Bytes](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rng.html#a387b33340abf4e1233426494059f61a9 "External link") - Generate an array of random bytes. * [dipki::Rng::Guid](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rng.html#a7388a8609da4617ca54662fe6093fd1a "External link") - Generate a random 36-character Global Unique IDentifier (GUID) string according to [RFC4122](https://datatracker.ietf.org/doc/html/rfc4122 "External link"). * [dipki::Rng::Initialize](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rng.html#a49d9a9c8d333976acfb17551bd22886d "External link") - Initialize the RNG generator using a seed file. * [dipki::Rng::InitializeEx](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rng.html#a2c709f37337b06ac4fd16c25c7682ffd "External link") - Query and initialize the RNG generator using Intel(R) DRNG, if available. * [dipki::Rng::Number](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rng.html#a07289bae32a6ddd89da54a4c20a3c85d "External link") - Generate a random integer in a given range. * [dipki::Rng::Octet](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rng.html#af53eacf51dd6fcb08333fea515c7cbc6 "External link") - Generate a single random octet (byte) * [dipki::Rng::UpdateSeedFile](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rng.html#ac97be2de93aab03d4caee358b0410bd8 "External link") - Update the RNG seed file with more entropy. * [dipki::Rsa::DecodeMsgForEncryption](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rsa.html#a9d25f8de0a038b0aa9b23c80f2f40b26 "External link") - Decode a message for encryption. * [dipki::Rsa::DecodeMsgForSignature](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rsa.html#a192f8d5de70c1eaa23720cd73f584697 "External link") - Extract digest (or digestinfo) from an EMSA-PKCS1-v1_5-encoded block. * [dipki::Rsa::Decrypt](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rsa.html#af10a5292171c8e7388e1de5a0231ade4 "External link") - Decrypt a message encrypted using an RSA encryption scheme. * [dipki::Rsa::EncodeMsgForEncryption](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rsa.html#a8a19ba663e9d41954b32f6e7ef82ab89 "External link") - Encode a message for encryption. * [dipki::Rsa::EncodeMsgForSignature](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rsa.html#ae0c921a06ec0cb1e7a12a44e92887646 "External link") - Encode a message for signature. * [dipki::Rsa::Encrypt](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rsa.html#a7a1985fcfbb3e85601fb5b45242669b6 "External link") - Encrypt a short message using RSA encryption. * [dipki::Rsa::FromXMLString](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rsa.html#abe9c8f1422fc92c7539cdaa7abe65717 "External link") - Return an RSA key string in internal format from an XML string. * [dipki::Rsa::GetPrivateKeyFromPFX](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rsa.html#a238dd633405d9a5174a6a1762db151e7 "External link") - Extract an encrypted private key from a PKCS-12 PKCS8ShroudedKeyBag, saving the output directly as a new file. * [dipki::Rsa::KeyBits](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rsa.html#a6f495276f394a1eb0764e67c7d710206 "External link") - Get number of significant bits in RSA key modulus. * [dipki::Rsa::KeyBytes](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rsa.html#a2f98ec43d53954c0eff33559b9ab07de "External link") - Get number of bytes (octets) in RSA key modulus. * [dipki::Rsa::KeyHashCode](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rsa.html#a2a29511d1ba843a5024f1f5e4fc1dc16 "External link") - Compute the hash code of an "internal" RSA public or private key string. * [dipki::Rsa::KeyIsPrivate](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rsa.html#a6978884750ddf44b09f4c71437034335 "External link") - Determine if keystring is a private key. * [dipki::Rsa::KeyMatch](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rsa.html#a50c94da4020db9255ef92080d6d4fe52 "External link") - Determine if a pair of "internal" RSA private and public key strings are matched. * [dipki::Rsa::KeyValue](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rsa.html#a128b7ef2bae278e6b0856439e43d2e8d "External link") - Extract a base64-encoded RSA key value from internal key string. * [dipki::Rsa::MakeKeys](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rsa.html#a48dfe8237977369f90405443169a1bce "External link") - Generate an RSA public/private key pair and save as two key files. * [dipki::Rsa::PublicKeyFromPrivate](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rsa.html#a32a2360cf76e4930b1a55950afdc6da4 "External link") - Get internal RSA public key string from an internal RSA private key string. * [dipki::Rsa::RawPrivate](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rsa.html#a50a88a4e9650c3e384e25135eb8e6dd5 "External link") - Transforms (that is, encrypts or decrypts) raw data using an RSA private key. * [dipki::Rsa::RawPublic](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rsa.html#aa9095099ada24c1489840cfa53ec83e3 "External link") - Transforms (that is, encrypts or decrypts) raw data using an RSA public key. * [dipki::Rsa::ReadPrivateKey](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rsa.html#a1e2eff6eac9764624ed7d9eaf23b8f7a "External link") - Read from a file or string containing a private key into an "internal" key string. * [dipki::Rsa::ReadPublicKey](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rsa.html#a2d73a8d0f5c72a5c8328d290351bedb6 "External link") - Read from a file or string containing a public key into an "internal" key string. * [dipki::Rsa::SaveEncKey](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rsa.html#a444982f3c1f80e8971f464eac6f47a26 "External link") - Save an internal RSA key string to an encrypted key file. * [dipki::Rsa::SaveKey](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rsa.html#a2ce90bf0f13cbb2098a34b838f7f1af2 "External link") - Save an internal RSA key string to a key file. * [dipki::Rsa::ToXMLString](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_rsa.html#a33afa8224f6a3d5a3142eddb9e223b70 "External link") - Return an XML string representation of an RSA internal key string. * [dipki::Sig::AlgName](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_sig.html#a9d41e8ab8d866dc5e3bb8ba3725fced8 "External link") - Get the algorithm name. * [dipki::Sig::GetHashNameFromSigAlg](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_sig.html#a397c5d60ef2db934035707797b10437e "External link") - Get the hash algorithm used in the signature algorithm. * [dipki::Sig::SignData](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_sig.html#a782ee97d4d716ecdc933e4bc1c9ec36c "External link") - Compute a signature value over data in a byte array. * [dipki::Sig::SignDigest](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_sig.html#adfc0752234cfe2bbd9f52f7b2e35edfd "External link") - Compute a signature value over a message digest value. * [dipki::Sig::SignFile](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_sig.html#aa011b65674d1c69b7ca1aafbb67fd0e0 "External link") - Compute a signature value over binary data in a file. * [dipki::Sig::VerifyData](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_sig.html#afc0d9cb74fe7cfb2ce610f5f9c8c74fc "External link") - Verify a signature value over data in a byte array. * [dipki::Sig::VerifyDigest](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_sig.html#a3c07eea0283ab8fcbafc9d8300a5f933 "External link") - Verify a signature value over a message digest value of data. * [dipki::Sig::VerifyFile](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_sig.html#a4434b77b3411712a19c8cbfc0109c3ea "External link") - Verify a signature value over data in a file. * [dipki::Smime::Extract](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_smime.html#a440c2d87ffd605a72a6ff1ee2e6b419f "External link") - Extract the body from an S/MIME entity. * [dipki::Smime::Query](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_smime.html#a1f6f809a61f7ac1b8680ffdf242a6757 "External link") - Query an S/MIME entity for selected information. * [dipki::Smime::Wrap](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_smime.html#a10d307291729cb54cdfdc5f4c11f3469 "External link") - Wrap a CMS object in an S/MIME entity. * [dipki::Wipe::Data](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_wipe.html#a6d3d230ff058e62ad26ec96f5b44d5d5 "External link") - Zeroise then clear data in memory. * [dipki::Wipe::File](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_wipe.html#a487b2823f03489759882f38617e15020 "External link") - Securely wipe and delete a file. * [dipki::Wipe::String](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_wipe.html#a7f4bcf4a0356d51efe7788b360bab3d4 "External link") - Zeroise then clear a string. * [dipki::X509::CertIsRevoked](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_x509.html#a32ce1e27f5d4ab8bc3fc795384439e8f "External link") - Check whether an X.509 certificate has been revoked in a given Certificate Revocation List (CRL). * [dipki::X509::CertIsValidNow](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_x509.html#ac6ef066faf9ca7d9c4e5b7d7d5a04973 "External link") - Verify that an X.509 certificate is currently valid as per system clock. * [dipki::X509::CertIsVerified](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_x509.html#a1532cfaef52bef714697a6728ee10c75 "External link") - Verify that an X.509 certificate has been signed by its issuer. * [dipki::X509::CertPathIsValid](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_x509.html#a32b16ee531722c941cce3eef8b9209d1 "External link") - Validate a certificate path. * [dipki::X509::CertRequest](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_x509.html#af0c4852b7eb96fe4be27dbb5eb738855 "External link") - Create a PKCS #10 certificate signing request (CSR). * [dipki::X509::CertThumb](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_x509.html#a42640b33c3c4c2745644b2c3f067ed21 "External link") - Calculate the thumbprint (message digest hash) of an X.509 certificate. * [dipki::X509::GetCertCountInP7Chain](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_x509.html#ab39028867279fae0db82bd281caedbc1 "External link") - Return number of certificates in a PKCS-7 "certs-only" certificate chain file. * [dipki::X509::GetCertFromP7Chain](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_x509.html#a08efea2f2eb7412bdbc0c47c9af25341 "External link") - Extract an X.509 certificate from a PKCS-7 "certs-only" certificate chain file, saving the output directly as a new file. * [dipki::X509::GetCertFromPFX](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_x509.html#a203c6c2df25242677aed1b245d945bfa "External link") - Extract an X.509 certificate from a PKCS-12 PFX/.p12 file, saving the output directly as a new file. * [dipki::X509::GetP7ChainFromPFX](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_x509.html#a3f55148aa5a2906b853b9ee95709779b "External link") - Extract all X.509 certificates from a PKCS-12 PFX/.p12 file, saving the output directly as a new PKCS-7 "certs-only" certificate chain file. * [dipki::X509::HashIssuerAndSN](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_x509.html#aab9ad8e8fa8aadf6df0c37c8a3ea89e1 "External link") - Return the hash of the issuer and serial number. * [dipki::X509::MakeCRL](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_x509.html#a8c1e71c90536e86f8f45a1f22af57d05 "External link") - Create an X.509 Certificate Revocation List (CRL). * [dipki::X509::MakeCert](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_x509.html#abc55dc55d87795a5eec2c6a2754d57ec "External link") - Create an X.509 certificate using subject's public key and issuer's private key. * [dipki::X509::MakeCertSelf](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_x509.html#a8f3dcd821cf4e2e614f9b859ffc8e675 "External link") - Create a self-signed X.509 certificate. * [dipki::X509::QueryCert](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_x509.html#ac7b07eccfbb6ed11d98abd9808119633 "External link") - Query an X.509 certificate file for selected information. * [dipki::X509::ReadCertStringFromP7Chain](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_x509.html#a340373ecfdf7a3d6560ef7f3829ad913 "External link") - Read an X.509 certificate into a base64 string from a PKCS-7 "certs-only" certificate chain file. * [dipki::X509::ReadCertStringFromPFX](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_x509.html#a737485c8b333f51e80f7eab8ca4dc978 "External link") - Read an X.509 certificate into a base64 string from PKCS-12 PFX/.p12 data. * [dipki::X509::ReadStringFromFile](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_x509.html#a44e353950105afd924a2b2cdede7e956 "External link") - Read an X.509 certificate into its base64 string representation. * [dipki::X509::SaveFileFromString](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_x509.html#aafcc3aa7a6a076b7f8f4dcb207e62fe4 "External link") - Create an X.509 certificate file from its base64 string representation. * [dipki::X509::TextDumpToString](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_x509.html#a9b8039568d9cd27430a5809956f06ed4 "External link") - Dump details of an X.509 certificate or a X.509 certificate revocation list (CRL) or a PKCS-10 certificate signing request (CSR) to a string. * [dipki::Xof::Bytes](https://cryptosys.net/pki/cpppki/html/classdipki_1_1_xof.html#a55cd586acc417fe248d8568bed801766 "External link") - Generate bytes using an extendable-output function (XOF). [[Contents](#topofpage)] [[Index](#index)] .NET Classes and Methods ------------------------------------------------------------ To program in the .NET languages C# and `VB.NET` (VB20xx), use the classes and methods in the CryptoSys PKI Pro .NET Class Library `diCrSysPKINet.dll`. There is a full listing of all the .NET methods at [List of .NET Methods](#methodlist). For more guidance on programming, see [Using with .NET: C# and `VB.NET`](#UsingWithDotNet). [[Contents](#topofpage)] [[Index](#index)] ### Cross-reference between Functions and .NET Methods The following table shows the cross-reference between the core VB6/C functions and the .NET methods. Plus, where relevant, the equivalent [VBA wrapper function](#vbawrapperfunctions). | Function | Equivalent .NET Method | VBA Wrapper | | --- | --- | --- | | [`ASN1_TextDump`](#ASN1_TextDump) | [Asn1.TextDump Method](#M_Asn1_TextDump) | | | [`ASN1_TextDumpToString`](#ASN1_TextDumpToString) | [Asn1.TextDumpToString Method](#M_Asn1_TextDumpToString) | `[asn1TextDumpToString](#VB_asn1TextDumpToString)` | | [`ASN1_Type`](#ASN1_Type) | [Asn1.Type Method](#M_Asn1_Type) | `[asn1Type](#VB_asn1Type)` | | [`CIPHER_Bytes`](#CIPHER_Bytes) - @deprecated | [Cipher.Encrypt Method](#M_Cipher_Encrypt_ByteByteByteCipherAlgorithmMode) (Byte[], Byte[], Byte[], CipherAlgorithm, Mode) [Cipher.Decrypt Method](#M_Cipher_Decrypt_ByteByteByteCipherAlgorithmMode) (Byte[], Byte[], Byte[], CipherAlgorithm, Mode) | | | [`CIPHER_DecryptAEAD`](#CIPHER_DecryptAEAD) | [Cipher.DecryptAEAD Method](#M_Cipher_DecryptAEAD_ByteByteByteAeadAlgorithm) (Byte[], Byte[], Byte[], AeadAlgorithm) [Cipher.DecryptAEAD Method](#M_Cipher_DecryptAEAD_ByteByteByteByteAeadAlgorithmCipher_Opts) (Byte[], Byte[], Byte[], Byte[], AeadAlgorithm, Cipher.Opts) | `[cipherDecryptAEAD](#VB_cipherDecryptAEAD)` | | [`CIPHER_DecryptBytes`](#CIPHER_DecryptBytes) | [Cipher.Decrypt Method](#M_Cipher_Decrypt_ByteByteByteCipherAlgorithmModePaddingCipher_Opts) (Byte[], Byte[], Byte[], CipherAlgorithm, Mode, Padding, Cipher.Opts) | `[cipherDecryptBytes](#VB_cipherDecryptBytes)` | | [`CIPHER_DecryptHex`](#CIPHER_DecryptHex) | [Cipher.Decrypt Method](#M_Cipher_Decrypt_StringStringStringCipherAlgorithmModePaddingCipher_Opts) (String, String, String, CipherAlgorithm, Mode, Padding, Cipher.Opts) | `[cipherDecryptHex](#VB_cipherDecryptHex)` | | [`CIPHER_EncryptAEAD`](#CIPHER_EncryptAEAD) | [Cipher.EncryptAEAD Method](#M_Cipher_EncryptAEAD_ByteByteByteAeadAlgorithm) (Byte[], Byte[], Byte[], AeadAlgorithm) [Cipher.EncryptAEAD Method](#M_Cipher_EncryptAEAD_ByteByteByteByteAeadAlgorithmCipher_Opts) (Byte[], Byte[], Byte[], Byte[], AeadAlgorithm, Cipher.Opts) | `[cipherEncryptAEAD](#VB_cipherEncryptAEAD)` | | [`CIPHER_EncryptBytes`](#CIPHER_EncryptBytes) | [Cipher.Encrypt Method](#M_Cipher_Encrypt_ByteByteByteCipherAlgorithmModePaddingCipher_Opts) (Byte[], Byte[], Byte[], CipherAlgorithm, Mode, Padding, Cipher.Opts) | `[cipherEncryptBytes](#VB_cipherEncryptBytes)` | | [`CIPHER_EncryptHex`](#CIPHER_EncryptHex) | [Cipher.Encrypt Method](#M_Cipher_Encrypt_StringStringStringCipherAlgorithmModePaddingCipher_Opts) (String, String, String, CipherAlgorithm, Mode, Padding, Cipher.Opts) | `[cipherEncryptHex](#VB_cipherEncryptHex)` | | [`CIPHER_File`](#CIPHER_File) - @deprecated | [Cipher.FileEncrypt Method](#M_Cipher_FileEncrypt_StringStringByteByteCipherAlgorithmModePaddingCipher_Opts) [Cipher.FileDecrypt Method](#M_Cipher_FileDecrypt_StringStringByteByteCipherAlgorithmModePaddingCipher_Opts) | | | [`CIPHER_FileDecrypt`](#CIPHER_FileDecrypt) | [Cipher.FileDecrypt Method](#M_Cipher_FileDecrypt_StringStringByteByteCipherAlgorithmModePaddingCipher_Opts) (String, String, Byte[], Byte[], CipherAlgorithm, Mode, Padding, Cipher.Opts) [Cipher.FileDecrypt Method](#M_Cipher_FileDecrypt_StringStringStringStringCipherAlgorithmModePaddingCipher_Opts) (String, String, String, String, CipherAlgorithm, Mode, Padding, Cipher.Opts) | `[cipherFileDecrypt](#VB_cipherFileDecrypt)` | | [`CIPHER_FileEncrypt`](#CIPHER_FileEncrypt) | [Cipher.FileEncrypt Method](#M_Cipher_FileEncrypt_StringStringByteByteCipherAlgorithmModePaddingCipher_Opts) (String, String, Byte[], Byte[], CipherAlgorithm, Mode, Padding, Cipher.Opts) [Cipher.FileEncrypt Method](#M_Cipher_FileEncrypt_StringStringStringStringCipherAlgorithmModePaddingCipher_Opts) (String, String, String, String, CipherAlgorithm, Mode, Padding, Cipher.Opts) | `[cipherFileEncrypt](#VB_cipherFileEncrypt)` | | [`CIPHER_Hex`](#CIPHER_Hex) | [Cipher.Encrypt Method](#M_Cipher_Encrypt_StringStringStringCipherAlgorithmMode) (String, String, String, CipherAlgorithm, Mode) [Cipher.Decrypt Method](#M_Cipher_Decrypt_StringStringStringCipherAlgorithmMode) (String, String, String, CipherAlgorithm, Mode) | | | [`CIPHER_KeyUnwrap`](#CIPHER_KeyUnwrap) | [Cipher.KeyUnwrap Method](#M_Cipher_KeyUnwrap) | `[cipherKeyUnwrap](#VB_cipherKeyUnwrap)` | | [`CIPHER_KeyWrap`](#CIPHER_KeyWrap) | [Cipher.KeyWrap Method](#M_Cipher_KeyWrap) | `[cipherKeyWrap](#VB_cipherKeyWrap)` | | [`CMS_GetSigDataDigest`](#CMS_GetSigDataDigest) | [Cms.GetSigDataDigest Method](#M_Cms_GetSigDataDigest) | `[cmsGetSigDataDigest](#VB_cmsGetSigDataDigest)` | | [`CMS_MakeComprData`](#CMS_MakeComprData) | [Cms.MakeComprData Method](#M_Cms_MakeComprData) | | | [`CMS_MakeDetachedSig`](#CMS_MakeDetachedSig) | [Cms.MakeDetachedSig Method](#M_Cms_MakeDetachedSig) | | | [`CMS_MakeEnvData`](#CMS_MakeEnvData) | [Cms.MakeEnvData Method](#M_Cms_MakeEnvData_StringStringStringCipherAlgorithmCms_EnvDataOptions) ( String, String, String, CipherAlgorithm, Cms.EnvDataOptions ) [Cms.MakeEnvData Method](#M_Cms_MakeEnvData_StringStringStringCipherAlgorithmCms_KeyEncrAlgorithmHashAlgorithmCms_EnvDataOptionsKdf_KdfAlgKdf_KeyWrapAlgStringInt32Cms_ContentEncrAlg) ( String, String, String, CipherAlgorithm, Cms.KeyEncrAlgorithm, HashAlgorithm, Cms.EnvDataOptions, KdfAlg, KeyWrapAlg, String, Int32, Cms.ContentEncrAlg) | `[cmsMakeEnvData](#VB_cmsMakeEnvData)` | | [`CMS_MakeEnvDataFromBytes`](#CMS_MakeEnvDataFromBytes) | [Cms.MakeEnvDataFromBytes Method](#M_Cms_MakeEnvDataFromBytes) | `[cmsMakeEnvDataFromBytes](#VB_cmsMakeEnvDataFromBytes)` | | [`CMS_MakeEnvDataFromString`](#CMS_MakeEnvDataFromString) | [Cms.MakeEnvDataFromString Method](#M_Cms_MakeEnvDataFromString_StringStringStringCipherAlgorithmCms_EnvDataOptions) (String, String, String, CipherAlgorithm, Cms.EnvDataOptions) [Cms.MakeEnvDataFromString Method](#M_Cms_MakeEnvDataFromString_StringStringStringCipherAlgorithmCms_KeyEncrAlgorithmHashAlgorithmCms_EnvDataOptionsKdf_KdfAlgKdf_KeyWrapAlgStringInt32Cms_ContentEncrAlg) (String, String, String, CipherAlgorithm, Cms.KeyEncrAlgorithm, HashAlgorithm, Cms.EnvDataOptions, KdfAlg, KeyWrapAlg, String, Int32, Cms.ContentEncrAlg) | `[cmsMakeEnvDataFromString](#VB_cmsMakeEnvDataFromString)` | | [`CMS_MakeSigData`](#CMS_MakeSigData) | [Cms.MakeSigData Method](#M_Cms_MakeSigData_StringStringStringStringCms_SigAlgCms_SigDataOptions) ( String, String, String, String, Cms.SigAlg, Cms.SigDataOptions) [Cms.MakeSigData Method](#M_Cms_MakeSigData_StringStringStringStringHashAlgorithmCms_SigDataOptions) ( String, String, String, String, HashAlgorithm, Cms.SigDataOptions) | | | [`CMS_MakeSigDataFromBytes`](#CMS_MakeSigDataFromBytes) | [Cms.MakeSigDataFromBytes Method](#M_Cms_MakeSigDataFromBytes) | `[cmsMakeSigDataFromBytes](#VB_cmsMakeSigDataFromBytes)` | | [`CMS_MakeSigDataFromSigValue`](#CMS_MakeSigDataFromSigValue) | [Cms.MakeSigDataFromSigValue Method](#M_Cms_MakeSigDataFromSigValue) [Cms.MakeSigDataFromPseudo Method](#M_Cms_MakeSigDataFromPseudo) | `[cmsMakeSigDataFromSigValue](#VB_cmsMakeSigDataFromSigValue)` | | [`CMS_MakeSigDataFromString`](#CMS_MakeSigDataFromString) | [Cms.MakeSigDataFromString Method](#M_Cms_MakeSigDataFromString_StringStringStringStringCms_SigAlgCms_SigDataOptions) (String, String, String, String, Cms.SigAlg, Cms.SigDataOptions) [Cms.MakeSigDataFromString Method](#M_Cms_MakeSigDataFromString_StringStringStringStringHashAlgorithmCms_SigDataOptions) (String, String, String, String, HashAlgorithm, Cms.SigDataOptions) | | | [`CMS_QueryEnvData`](#CMS_QueryEnvData) | [Cms.QueryEnvData Method](#M_Cms_QueryEnvData) | `[cmsQueryEnvData](#VB_cmsQueryEnvData)` | | [`CMS_QuerySigData`](#CMS_QuerySigData) | [Cms.QuerySigData Method](#M_Cms_QuerySigData) | `[cmsQuerySigData](#VB_cmsQuerySigData)` | | [`CMS_ReadComprData`](#CMS_ReadComprData) | [Cms.ReadComprData Method](#M_Cms_ReadComprData) | | | [`CMS_ReadEnvData`](#CMS_ReadEnvData) | [Cms.ReadEnvDataToFile Method](#M_Cms_ReadEnvDataToFile) | | | [`CMS_ReadEnvDataToBytes`](#CMS_ReadEnvDataToBytes) | [Cms.ReadEnvDataToBytes Method](#M_Cms_ReadEnvDataToBytes) | `[cmsReadEnvDataToBytes](#VB_cmsReadEnvDataToBytes)` | | [`CMS_ReadEnvDataToString`](#CMS_ReadEnvDataToString) | [Cms.ReadEnvDataToString Method](#M_Cms_ReadEnvDataToString) | `[cmsReadEnvDataToString](#VB_cmsReadEnvDataToString)` | | [`CMS_ReadSigData`](#CMS_ReadSigData) | [Cms.ReadSigDataToFile Method](#M_Cms_ReadSigDataToFile) | | | [`CMS_ReadSigDataToBytes`](#CMS_ReadSigDataToBytes) | [Cms.ReadSigDataToBytes Method](#M_Cms_ReadSigDataToBytes) | `[cmsReadSigDataToBytes](#VB_cmsReadSigDataToBytes)` | | [`CMS_ReadSigDataToString`](#CMS_ReadSigDataToString) | [Cms.ReadSigDataToString Method](#M_Cms_ReadSigDataToString) | `[cmsReadSigDataToString](#VB_cmsReadSigDataToString)` | | [`CMS_VerifySigData`](#CMS_VerifySigData) | [Cms.VerifySigData Method](#M_Cms_VerifySigData) | `[cmsVerifySigData](#VB_cmsVerifySigData)` | | [`CNV_B64Filter`](#CNV_B64Filter) | [Cnv.Base64Filter Method](#M_Cnv_Base64Filter) | `[cnvB64Filter](#VB_cnvB64Filter)` | | [`CNV_B64StrFromBytes`](#CNV_B64StrFromBytes) | [Cnv.ToBase64 Method](#M_Cnv_ToBase64_Byte) (Byte[]) [Cnv.ToBase64 Method](#M_Cnv_ToBase64_String) (String) | `[cnvToBase64](#VB_cnvToBase64)` | | [`CNV_Base58FromBytes`](#CNV_Base58FromBytes) | [Cnv.ToBase58 Method](#M_Cnv_ToBase58) | `[cnvBase58FromBytes](#VB_cnvBase58FromBytes)` | | [`CNV_Base58ToBytes`](#CNV_Base58ToBytes) | [Cnv.FromBase58 Method](#M_Cnv_FromBase58) | `[cnvBase58ToBytes](#VB_cnvBase58ToBytes)` | | [`CNV_ByteEncoding`](#CNV_ByteEncoding) | [Cnv.ByteEncoding Method](#M_Cnv_ByteEncoding) | `[cnvByteEncoding](#VB_cnvByteEncoding)` | | [`CNV_BytesFromB64Str`](#CNV_BytesFromB64Str) | [Cnv.FromBase64 Method](#M_Cnv_FromBase64) | `[cnvFromBase64](#VB_cnvFromBase64)` | | [`CNV_BytesFromHexStr`](#CNV_BytesFromHexStr) | [Cnv.FromHex Method](#M_Cnv_FromHex) | `[cnvFromHex](#VB_cnvFromHex)` | | [`CNV_CheckUTF8`](#CNV_CheckUTF8) - @deprecated | Not applicable in .NET | | | [`CNV_CheckUTF8Bytes`](#CNV_CheckUTF8Bytes) | [Cnv.CheckUTF8 Method](#M_Cnv_CheckUTF8) (Byte[]) | `[cnvCheckUTF8Bytes](#VB_cnvCheckUTF8Bytes)` | | [`CNV_CheckUTF8File`](#CNV_CheckUTF8File) | [Cnv.CheckUTF8File Method](#M_Cnv_CheckUTF8File) | | | [`CNV_HexFilter`](#CNV_HexFilter) | [Cnv.HexFilter Method](#M_Cnv_HexFilter) | `[cnvHexFilter](#VB_cnvHexFilter)` | | [`CNV_HexStrFromBytes`](#CNV_HexStrFromBytes) | [Cnv.ToHex Method](#M_Cnv_ToHex_Byte) | `[cnvToHex](#VB_cnvToHex)` | | [`CNV_Latin1FromUTF8`](#CNV_Latin1FromUTF8) - @deprecated | Not applicable in .NET | | | [`CNV_Latin1FromUTF8Bytes`](#CNV_Latin1FromUTF8Bytes) | Use `System.Text.Encoding.UTF8.GetString(bytes)`. | `[cnvLatin1FromUTF8Bytes](#VB_cnvLatin1FromUTF8Bytes)` | | [`CNV_NumFromBytes`](#CNV_NumFromBytes) | [Cnv.NumFromBytes Method](#M_Cnv_NumFromBytes) | `[cnvNumFromBytes](#VB_cnvNumFromBytes)` | | [`CNV_NumToBytes`](#CNV_NumToBytes) | [Cnv.NumToBytes Method](#M_Cnv_NumToBytes) | `[cnvNumToBytes](#VB_cnvNumToBytes)` | | [`CNV_ReverseBytes`](#CNV_ReverseBytes) | [Cnv.ReverseBytes Method](#M_Cnv_ReverseBytes) | `[cnvReverseBytes](#VB_cnvReverseBytes)` | | [`CNV_ShortPathName`](#CNV_ShortPathName) | [Cnv.ShortPathName Method](#M_Cnv_ShortPathName) | | | [`CNV_UTF8BytesFromLatin1`](#CNV_UTF8BytesFromLatin1) | Use `System.Text.Encoding.UTF8.GetBytes(Str)`. | `[cnvUTF8BytesFromLatin1](#VB_cnvUTF8BytesFromLatin1)` | | [`CNV_UTF8FromLatin1`](#CNV_UTF8FromLatin1) - @deprecated | Not applicable in .NET | | | [`COMPR_Compress`](#COMPR_Compress) | [Compr.Compress Method](#M_Compr_Compress) | `[comprCompress](#VB_comprCompress)` | | [`COMPR_Uncompress`](#COMPR_Uncompress) | [Compr.Uncompress Method](#M_Compr_Uncompress) | `[comprUncompress](#VB_comprUncompress)` | | [`ECC_DHSharedSecret`](#ECC_DHSharedSecret) | [Ecc.DHSharedSecret Method](#M_Ecc_DHSharedSecret) | `[eccDHSharedSecret](#VB_eccDHSharedSecret)` | | [`ECC_KeyHashCode`](#ECC_KeyHashCode) | [Ecc.KeyHashCode Method](#M_Ecc_KeyHashCode) | `[eccKeyHashCode](#VB_eccKeyHashCode)` | | [`ECC_MakeKeys`](#ECC_MakeKeys) | [Ecc.MakeKeys Method](#M_Ecc_MakeKeys) | `[eccMakeKeys](#VB_eccMakeKeys)` | | [`ECC_PublicKeyFromPrivate`](#ECC_PublicKeyFromPrivate) | [Ecc.PublicKeyFromPrivate Method](#M_Ecc_PublicKeyFromPrivate) | `[eccPublicKeyFromPrivate](#VB_eccPublicKeyFromPrivate)` | | [`ECC_QueryKey`](#ECC_QueryKey) | [Ecc.QueryKey Method](#M_Ecc_QueryKey) | `[eccQueryKey](#VB_eccQueryKey)` | | [`ECC_ReadKeyByCurve`](#ECC_ReadKeyByCurve) | [Ecc.ReadKeyByCurve Method](#M_Ecc_ReadKeyByCurve) | `[eccReadKeyByCurve](#VB_eccReadKeyByCurve)` | | [`ECC_ReadPrivateKey`](#ECC_ReadPrivateKey) | [Ecc.ReadPrivateKey Method](#M_Ecc_ReadPrivateKey) | `[eccReadPrivateKey](#VB_eccReadPrivateKey)` | | [`ECC_ReadPublicKey`](#ECC_ReadPublicKey) | [Ecc.ReadPublicKey Method](#M_Ecc_ReadPublicKey) | `[eccReadPublicKey](#VB_eccReadPublicKey)` | | [`ECC_SaveEncKey`](#ECC_SaveEncKey) | [Ecc.SaveEncKey Method](#M_Ecc_SaveEncKey) | `[eccSaveEncKey](#VB_eccSaveEncKey)` | | [`ECC_SaveKey`](#ECC_SaveKey) | [Ecc.SaveKey Method](#M_Ecc_SaveKey) | `[eccSaveKey](#VB_eccSaveKey)` | | [`HASH_Bytes`](#HASH_Bytes) | [Hash.BytesFromBytes Method](#M_Hash_BytesFromBytes) [Hash.Double Method](#M_Hash_Double) | `[hashBytes](#VB_hashBytes)` | | [`HASH_File`](#HASH_File) | [Hash.BytesFromFile Method](#M_Hash_BytesFromFile) | `[hashFile](#VB_hashFile)` | | [`HASH_HexFromBytes`](#HASH_HexFromBytes) | [Hash.HexFromBytes Method](#M_Hash_HexFromBytes) [Hash.HexFromString Method](#M_Hash_HexFromString) | `[hashHexFromBytes](#VB_hashHexFromBytes)` | | [`HASH_HexFromFile`](#HASH_HexFromFile) | [Hash.HexFromFile Method](#M_Hash_HexFromFile) [Hash.HexFromTextFile Method](#M_Hash_HexFromTextFile) | `[hashHexFromFile](#VB_hashHexFromFile)` | | [`HASH_HexFromHex`](#HASH_HexFromHex) | [Hash.HexFromHex Method](#M_Hash_HexFromHex) | `[hashHexFromHex](#VB_hashHexFromHex)` | | [`HASH_Length`](#HASH_Length) | [Hash.Length Method](#M_Hash_Length) | `[hashLength](#VB_hashLength)` | | [`HMAC_Bytes`](#HMAC_Bytes) | [Hmac.BytesFromBytes Method](#M_Hmac_BytesFromBytes) | `[hmacBytes](#VB_hmacBytes)` | | [`HMAC_HexFromBytes`](#HMAC_HexFromBytes) | [Hmac.HexFromBytes Method](#M_Hmac_HexFromBytes) | `[hmacHexFromBytes](#VB_hmacHexFromBytes)` | | [`HMAC_HexFromHex`](#HMAC_HexFromHex) | [Hmac.HexFromHex Method](#M_Hmac_HexFromHex) | `[hmacHexFromHex](#VB_hmacHexFromHex)` | | [`KDF_Bytes`](#KDF_Bytes) | [Kdf.Bytes Method](#M_Kdf_Bytes) | `[kdfBytes](#VB_kdfBytes)` | | [`HPKE_DerivePrivateKey`](#HPKE_DerivePrivateKey) | [Hpke.DerivePrivateKey Method](#M_Hpke_DerivePrivateKey) | `[hpkeDerivePrivateKey](#VB_hpkeDerivePrivateKey)` | | [`HPKE_LabeledExpand`](#HPKE_LabeledExpand) | [Hpke.LabeledExpand Method](#M_Hpke_LabeledExpand) | `[hpkeLabeledExpand](#VB_hpkeLabeledExpand)` | | [`HPKE_LabeledExtract`](#HPKE_LabeledExtract) | [Hpke.LabeledExtract Method](#M_Hpke_LabeledExtract) | `[hpkeLabeledExtract](#VB_hpkeLabeledExtract)` | | [`KDF_ForCms`](#KDF_ForCms) | [Kdf.ForCms Method](#M_Kdf_ForCms) | `[kdfForCms](#VB_kdfForCms)` | | [`OCSP_MakeRequest`](#OCSP_MakeRequest) | [Ocsp.MakeRequest Method](#M_Ocsp_MakeRequest) | `[ocspMakeRequest](#VB_ocspMakeRequest)` | | [`OCSP_ReadResponse`](#OCSP_ReadResponse) | [Ocsp.ReadResponse Method](#M_Ocsp_ReadResponse) | `[ocspReadResponse](#VB_ocspReadResponse)` | | [`PAD_BytesBlock`](#PAD_BytesBlock) | [Cipher.Pad Method](#M_Cipher_Pad_ByteCipherAlgorithmPadding) | `[padBytesBlock](#VB_padBytesBlock)` | | [`PAD_HexBlock`](#PAD_HexBlock) | [Cipher.Pad Method](#M_Cipher_Pad_StringCipherAlgorithmPadding) (String, CipherAlgorithm, Padding) | `[padHexBlock](#VB_padHexBlock)` | | [`PAD_UnpadBytes`](#PAD_UnpadBytes) | [Cipher.Unpad Method](#M_Cipher_Unpad_ByteCipherAlgorithmPadding) (Byte[], CipherAlgorithm, Padding) | `[padUnpadBytes](#VB_padUnpadBytes)` | | [`PAD_UnpadHex`](#PAD_UnpadHex) | [Cipher.Pad Method](#M_Cipher_Unpad_StringCipherAlgorithmPadding) (String, CipherAlgorithm, Padding) | `[padUnpadHex](#VB_padUnpadHex)` | | [`PBE_Kdf2`](#PBE_Kdf2) | [Pbe.Kdf2 Method](#M_Pbe_Kdf2_Int32ByteByteInt32HashAlgorithm) (Int32, Byte[], Byte[], Int32, HashAlgorithm) | `[pbeKdf2](#VB_pbeKdf2)` | | [`PBE_Kdf2Hex`](#PBE_Kdf2Hex) | [Pbe.Kdf2 Method](#M_Pbe_Kdf2_Int32StringStringInt32HashAlgorithm) (Int32, String, String, Int32, HashAlgorithm) | `[pbeKdf2Hex](#VB_pbeKdf2Hex)` | | [`PBE_Scrypt`](#PBE_Scrypt) | [Pbe.Scrypt Method](#M_Pbe_Scrypt_Int32ByteByteInt32Int32Int32) | `[pbeScrypt](#VB_pbeScrypt)` | | [`PBE_ScryptHex`](#PBE_ScryptHex) | [Pbe.Scrypt Method](#M_Pbe_Scrypt_Int32StringStringInt32Int32Int32) | `[pbeScryptHex](#VB_pbeScryptHex)` | | [`PEM_FileFromBinFile`](#PEM_FileFromBinFile) [`PEM_FileFromBinFileEx`](#PEM_FileFromBinFileEx) | [Pem.FileFromBinFile Method](#M_Pem_FileFromBinFile) Pem.FileFromBinFile Method | | | [`PEM_FileToBinFile`](#PEM_FileToBinFile) | [Pem.FileToBinFile Method](#M_Pem_FileToBinFile) | | | [`PFX_MakeFile`](#PFX_MakeFile) | [Pfx.MakeFile Method](#M_Pfx_MakeFile) | `[pfxMakeFile](#VB_pfxMakeFile)` | | [`PFX_VerifySig`](#PFX_VerifySig) | [Pfx.SignatureIsValid Method](#M_Pfx_SignatureIsValid) | | | [`PKI_CompileTime`](#PKI_CompileTime) | [General.CompileTime Method](#M_General_CompileTime) | `[pkiCompileTime](#VB_pkiCompileTime)` | | [`PKI_ErrorCode`](#PKI_ErrorCode) | [General.ErrorCode Method](#M_General_ErrorCode) | `[pkiErrorCode](#VB_pkiErrorCode)` | | [`PKI_ErrorLookup`](#PKI_ErrorLookup) | [General.ErrorLookup Method](#M_General_ErrorLookup) | `[pkiErrorLookup](#VB_pkiErrorLookup)` | | [`PKI_FormatErrorMessage`](#PKI_FormatErrorMessage) | [General.FormatErrorMessage Method](#M_General_FormatErrorMessage) | `[errFormatErrorMessage](#VB_errFormatErrorMessage)` | | [`PKI_LastError`](#PKI_LastError) | [General.LastError Method](#M_General_LastError) | `[pkiLastError](#VB_pkiLastError)` | | [`PKI_LicenceType`](#PKI_LicenceType) | [General.LicenceType Method](#M_General_LicenceType) | `[pkiLicenceType](#VB_pkiLicenceType)` | | [`PKI_ModuleInfo`](#PKI_ModuleInfo) | [General.ModuleInfo Method](#M_General_ModuleInfo) | `[pkiModuleInfo](#VB_pkiModuleInfo)` | | [`PKI_ModuleName`](#PKI_ModuleName) | [General.ModuleName Method](#M_General_ModuleName) | `[pkiModuleName](#VB_pkiModuleName)` | | [`PKI_Platform`](#PKI_Platform) | [General.Platform Method](#M_General_Platform) | `[pkiPlatform](#VB_pkiPlatform)` | | [`PKI_PowerUpTests`](#PKI_PowerUpTests) | [General.PowerUpTests Method](#M_General_PowerUpTests) | | | [`PKI_Version`](#PKI_Version) | [General.Version Method](#M_General_Version) | `[pkiVersion](#VB_pkiVersion)` | | [`PRF_Bytes`](#PRF_Bytes) | [Prf.Bytes Method](#M_Prf_Bytes) | [`prfBytes`](#VB_prfBytes) | | [`PWD_Prompt`](#PWD_Prompt) [`PWD_PromptEx`](#PWD_PromptEx) | [Pwd.Prompt Method](#M_Pwd_Prompt) | `[pwdPrompt](#VB_pwdPrompt)` | | [`RNG_Bytes`](#RNG_Bytes) | [Rng.Bytes Method](#M_Rng_Bytes_Int32) (Int32) [Rng.Bytes Method](#M_Rng_Bytes_Int32Byte) (Int32, Byte) [Rng.Bytes Method](#M_Rng_Bytes_Int32String) (Int32, String) | `[rngBytes](#VB_rngBytes)` | | [`RNG_BytesWithPrompt`](#RNG_BytesWithPrompt) | [Rng.BytesWithPrompt Method](#M_Rng_BytesWithPrompt_Int32Rng_Strength) (Int32, Rng.Strength) [Rng.BytesWithPrompt Method](#M_Rng_BytesWithPrompt_Int32StringRng_Strength) (Int32, String, Rng.Strength) | | | [`RNG_Guid`](#RNG_Guid) | [Rng.Guid Method](#M_Rng_Guid) | `[rngGuid](#VB_rngGuid)` | | [`RNG_Initialize`](#RNG_Initialize) | [Rng.Initialize Method](#M_Rng_Initialize) [Rng.InitializeEx Method](#M_Rng_InitializeEx) | `[rngInitialize](#VB_rngInitialize)` `[rngInitializeEx](#VB_rngInitializeEx)` | | [`RNG_MakeSeedFile`](#RNG_MakeSeedFile) | [Rng.MakeSeedFile Method](#M_Rng_MakeSeedFile) | | | [`RNG_Number`](#RNG_Number) | [Rng.Number Method](#M_Rng_Number) [Rng.Octet Method](#M_Rng_Octet) | | | [`RNG_String`](#RNG_String) - @deprecated | Not applicable | | | [`RNG_StringWithPrompt`](#RNG_StringWithPrompt) - @deprecated | Not applicable | | | [`RNG_Test`](#RNG_Test) | [Rng.Test Method](#M_Rng_Test) | | | [`RNG_TestDRBGVS`](#RNG_TestDRBGVS) | [Rng.TestDrbgvs Method](#M_Rng_TestDrbgvs) | | | [`RNG_UpdateSeedFile`](#RNG_UpdateSeedFile) | [Rng.UpdateSeedFile Method](#M_Rng_UpdateSeedFile) | | | [`RSA_CheckKey`](#RSA_CheckKey) | [Rsa.CheckKey Method](#M_Rsa_CheckKey_String) (String) [Rsa.CheckKey Method](#M_Rsa_CheckKey_StringBuilder) (StringBuilder) | | | [`RSA_DecodeMsg`](#RSA_DecodeMsg) | [Rsa.DecodeMsgForEncryption Method](#M_Rsa_DecodeMsgForEncryption) [Rsa.DecodeDigestForSignature Method](#M_Rsa_DecodeDigestForSignature) [Rsa.DecodeMsgIso9796 Method](#M_Rsa_DecodeMsgIso9796) | `[rsaDecodeMsg](#VB_rsaDecodeMsg)` | | [`RSA_Decrypt`](#RSA_Decrypt) | [Rsa.Decrypt Method](#M_Rsa_Decrypt) | `[rsaDecrypt](#VB_rsaDecrypt)` | | [`RSA_EncodeMsg`](#RSA_EncodeMsg) | [Rsa.EncodeMsgForEncryption Method](#M_Rsa_EncodeMsgForEncryption) [Rsa.EncodeMsgForSignature Method](#M_Rsa_EncodeMsgForSignature) [Rsa.EncodeDigestForSignature Method](#M_Rsa_EncodeDigestForSignature) [Rsa.EncodeMsgIso9796 Method](#M_Rsa_EncodeMsgIso9796) | `[rsaEncodeMsg](#VB_rsaEncodeMsg)` | | [`RSA_Encrypt`](#RSA_Encrypt) | [Rsa.Encrypt Method](#M_Rsa_Encrypt) | `[rsaEncrypt](#VB_rsaEncrypt)` | | [`RSA_FromXMLString`](#RSA_FromXMLString) | [Rsa.FromXMLString Method (String)](#M_Rsa_FromXMLString_String) [Rsa.FromXMLString Method (String, Rsa.XmlOptions)](#M_Rsa_FromXMLString_StringRsa_XmlOptions) [Rsa.FromXMLString Method (String, Boolean)](#M_Rsa_FromXMLString_StringBoolean) | `[rsaFromXMLString](#VB_rsaFromXMLString)` | | [`RSA_GetPrivateKeyFromPFX`](#RSA_GetPrivateKeyFromPFX) | [Rsa.GetPrivateKeyFromPFX Method](#M_Rsa_GetPrivateKeyFromPFX) | | | [`RSA_GetPublicKeyFromCert`](#RSA_GetPublicKeyFromCert) - @deprecated | [Rsa.GetPublicKeyFromCert Method](#M_Rsa_GetPublicKeyFromCert) - @deprecated | | | [`RSA_KeyBits`](#RSA_KeyBits) | [Rsa.KeyBits Method](#M_Rsa_KeyBits_String) (String) [Rsa.KeyBits Method](#M_Rsa_KeyBits_StringBuilder) (StringBuilder) | `[rsaKeyBits](#VB_rsaKeyBits)` | | [`RSA_KeyBytes`](#RSA_KeyBytes) | [Rsa.KeyBytes Method](#M_Rsa_KeyBytes_String) (String) [Rsa.KeyBytes Method](#M_Rsa_KeyBytes_StringBuilder) (StringBuilder) | `[rsaKeyBytes](#VB_rsaKeyBytes)` | | [`RSA_KeyHashCode`](#RSA_KeyHashCode) | [Rsa.KeyHashCode Method](#M_Rsa_KeyHashCode_String) (String) [Rsa.KeyHashCode Method](#M_Rsa_KeyHashCode_StringBuilder) (StringBuilder) | | | [`RSA_KeyMatch`](#RSA_KeyMatch) | [Rsa.KeyMatch Method](#M_Rsa_KeyMatch_StringString) (String) [Rsa.KeyMatch Method](#M_Rsa_KeyMatch_StringBuilderStringBuilder) (StringBuilder) | | | [`RSA_KeyValue`](#RSA_KeyValue) | [Rsa.KeyValue Method](#M_Rsa_KeyValue) | `[rsaKeyValue](#VB_rsaKeyValue)` | | [`RSA_MakeKeys`](#RSA_MakeKeys) - @deprecated | [Rsa.MakeKeys Method](#M_Rsa_MakeKeys_StringStringInt32Rsa_PublicExponentInt32StringRsa_PbeOptionsBooleanByte) (String, String, Int32, Rsa.PublicExponent, Int32, String, Rsa.PbeOptions, Boolean, Byte[]) [Rsa.MakeKeys Method](#M_Rsa_MakeKeys_StringStringInt32Rsa_PublicExponentInt32StringCipherAlgorithmHashAlgorithmRsa_FormatBoolean) (String, String, Int32, Rsa.PublicExponent, Int32, String, CipherAlgorithm, HashAlgorithm, Rsa.Format, Boolean) | `[rsaMakeKeys](#VB_rsaMakeKeys)` | | [`RSA_MakeKeysXtd`](#RSA_MakeKeysXtd) | [Rsa.MakeKeys Method](#M_Rsa_MakeKeys_StringStringStringInt32Rsa_PublicExponentRsa_PbeOptionsStringRsa_FormatBoolean) (String, String, String, Int32, Rsa.PublicExponent, Rsa.PbeOptions, String, Rsa.Format, Boolean) | `[rsaMakeKeys](#VB_rsaMakeKeys)` | | [`RSA_PublicKeyFromPrivate`](#RSA_PublicKeyFromPrivate) | [Rsa.PublicKeyFromPrivate Method](#M_Rsa_PublicKeyFromPrivate) | `[rsaPublicKeyFromPrivate](#VB_rsaPublicKeyFromPrivate)` | | [`RSA_RawPrivate`](#RSA_RawPrivate) | [Rsa.RawPrivate Method](#M_Rsa_RawPrivate_ByteString) (Byte[], String) [Rsa.RawPrivate Method](#M_Rsa_RawPrivate_ByteStringInt32) (Byte[], String, Int32) | `[rsaRawPrivate](#VB_rsaRawPrivate)` | | [`RSA_RawPublic`](#RSA_RawPublic) | [Rsa.RawPublic Method](#M_Rsa_RawPublic_ByteString) (Byte[], String) [Rsa.RawPublic Method](#M_Rsa_RawPublic_ByteStringInt32) (Byte[], String, Int32) | `[rsaRawPublic](#VB_rsaRawPublic)` | | [`RSA_ReadAnyPrivateKey`](#RSA_ReadAnyPrivateKey) | [Rsa.ReadPrivateKey Method](#M_Rsa_ReadPrivateKey) | `[rsaReadPrivateKey](#VB_rsaReadPrivateKey)` `[rsaReadAnyPrivateKey](#VB_rsaReadAnyPrivateKey)` | | [`RSA_ReadAnyPublicKey`](#RSA_ReadAnyPublicKey) | [Rsa.ReadPublicKey Method](#M_Rsa_ReadPublicKey) | `[rsaReadPublicKey](#VB_rsaReadPublicKey)` `[rsaReadAnyPublicKey](#VB_rsaReadAnyPublicKey)` | | [`RSA_ReadEncPrivateKey`](#RSA_ReadEncPrivateKey) - @deprecated | [Rsa.ReadEncPrivateKey Method](#M_Rsa_ReadEncPrivateKey) - @deprecated | | | [`RSA_ReadPrivateKeyFromPFX`](#RSA_ReadPrivateKeyFromPFX) - @deprecated | [Rsa.ReadPrivateKeyFromPFX Method](#M_Rsa_ReadPrivateKeyFromPFX) - @deprecated | | | [`RSA_ReadPrivateKeyInfo`](#RSA_ReadPrivateKeyInfo) - @deprecated | [Rsa.ReadPrivateKeyInfo Method](#M_Rsa_ReadPrivateKeyInfo) - @deprecated | | | [`RSA_ReadPublicKey`](#RSA_ReadPublicKey) - @deprecated | [Rsa.ReadPublicKey Method](#M_Rsa_ReadPublicKey) | `[rsaReadPublicKey](#VB_rsaReadPublicKey)` | | [`RSA_SaveEncKey`](#RSA_SaveEncKey) | [Rsa.SaveEncKey Method](#M_Rsa_SaveEncKey) | `[rsaSaveEncKey](#VB_rsaSaveEncKey)` | | [`RSA_SaveEncPrivateKey`](#RSA_SaveEncPrivateKey) | [Rsa.SaveEncPrivateKey Method](#M_Rsa_SaveEncPrivateKey_StringStringInt32StringRsa_PbeOptionsRsa_Format) (String, String, Int32, String, Rsa.PbeOptions, Rsa.Format) [Rsa.SaveEncPrivateKey Method](#M_Rsa_SaveEncPrivateKey_StringStringInt32StringCipherAlgorithmHashAlgorithmRsa_Format) (String, String, Int32, String, CipherAlgorithm, HashAlgorithm, Rsa.Format) | `[rsaSaveEncKey](#VB_rsaSaveEncKey)` | | [`RSA_SavePrivateKeyInfo`](#RSA_SavePrivateKeyInfo) | [Rsa.SavePrivateKeyInfo Method](#M_Rsa_SavePrivateKeyInfo) | `[rsaSaveKey](#VB_rsaSaveKey)` | | [`RSA_SavePublicKey`](#RSA_SavePublicKey) | [Rsa.SavePublicKey Method](#M_Rsa_SavePublicKey) | `[rsaSaveKey](#VB_rsaSaveKey)` | | [`RSA_ToXMLString`](#RSA_ToXMLString) | [Rsa.ToXMLString Method (String, Rsa.XmlOptions)](#M_Rsa_ToXMLString_StringRsa_XmlOptions) | `[rsaToXMLString](#VB_rsaToXMLString)` | | [`RSA_ToXMLStringEx`](#RSA_ToXMLStringEx) | [Rsa.ToXMLString Method (String, String, Rsa.XmlOptions)](#M_Rsa_ToXMLString_StringStringRsa_XmlOptions) | `[rsaToXMLStringEx](#VB_rsaToXMLStringEx)` | | [`SIG_SignData`](#SIG_SignData) | [Sig.SignData Method](#M_Sig_SignData) [Sig.SignDigest Method](#M_Sig_SignDigest) | `[sigSignData](#VB_sigSignData)` | | [`SIG_SignFile`](#SIG_SignFile) | [Sig.SignFile Method](#M_Sig_SignFile) | `[sigSignFile](#VB_sigSignFile)` | | [`SIG_VerifyData`](#SIG_VerifyData) | [Sig.VerifyData Method](#M_Sig_VerifyData) [Sig.VerifyDigest Method](#M_Sig_VerifyDigest) | `[sigVerifyData](#VB_sigVerifyData)` | | [`SIG_VerifyFile`](#SIG_VerifyFile) | [Sig.VerifyFile Method](#M_Sig_VerifyFile) (String, String, String, SigAlgorithm, Sig.VerifyOpts) | | | [`SMIME_Extract`](#SMIME_Extract) | [Smime.Extract Method](#M_Smime_Extract) | | | [`SMIME_Query`](#SMIME_Query) | [Smime.Query Method](#M_Smime_Query) | `[smimeQuery](#VB_smimeQuery)` | | [`SMIME_Wrap`](#SMIME_Wrap) | [Smime.Wrap Method](#M_Smime_Wrap) | | | [`TDEA_B64Mode`](#TDEA_B64Mode) | [Tdea.Encrypt Method](#M_Tdea_Encrypt_StringStringModeStringEncodingBase) (String, String, Mode, String, EncodingBase) [Tdea.Decrypt Method](#M_Tdea_Decrypt_StringStringModeStringEncodingBase) (String, String, Mode, String, EncodingBase) | | | [`TDEA_BytesMode`](#TDEA_BytesMode) | [Tdea.Encrypt Method](#M_Tdea_Encrypt_ByteByteModeByte) (Byte[], Byte[], Mode, Byte[]) [Tdea.Decrypt Method](#M_Tdea_Decrypt_ByteByteModeByte) (Byte[], Byte[], Mode, Byte[]) | | | [`TDEA_File`](#TDEA_File) | [Tdea.FileEncrypt Method](#M_Tdea_FileEncrypt_StringStringByteModeByte) (String, String, Byte[], Mode, Byte[]) [Tdea.FileDecrypt Method](#M_Tdea_FileDecrypt_StringStringByteModeByte) (String, String, Byte[], Mode, Byte[]) | | | [`TDEA_HexMode`](#TDEA_HexMode) | [Tdea.Encrypt Method](#M_Tdea_Encrypt_StringStringModeString) (String, String, Mode, String) [Tdea.Decrypt Method](#M_Tdea_Decrypt_StringStringModeString) (String, String, Mode, String) | | | [`WIPE_Data`](#WIPE_Data) | [Wipe.Data Method](#M_Wipe_Data) [Wipe.String Method](#M_Wipe_String) | `[wipeBytes](#VB_wipeBytes)` `[wipeString](#VB_wipeString)` | | [`WIPE_File`](#WIPE_File) | [Wipe.File Method](#M_Wipe_File) | | | [`X509_CertExpiresOn`](#X509_CertExpiresOn) | [X509.CertExpiresOn Method](#M_X509_CertExpiresOn) | | | [`X509_CertIssuedOn`](#X509_CertIssuedOn) | [X509.CertIssuedOn Method](#M_X509_CertIssuedOn) | | | [`X509_CertIssuerName`](#X509_CertIssuerName) | [X509.CertIssuerName Method](#M_X509_CertIssuerName) | | | [`X509_CertIsValidNow`](#X509_CertIsValidNow) | [X509.CertIsValidNow Method](#M_X509_CertIsValidNow) | | | [`X509_CertRequest`](#X509_CertRequest) | [X509.CertRequest Method](#M_X509_CertRequest) | | | [`X509_CertSerialNumber`](#X509_CertSerialNumber) | [X509.CertSerialNumber Method](#M_X509_CertSerialNumber) | | | [`X509_CertSubjectName`](#X509_CertSubjectName) | [X509.CertSubjectName Method](#M_X509_CertSubjectName) | | | [`X509_CertThumb`](#X509_CertThumb) | [X509.CertThumb Method](#M_X509_CertThumb) | `[x509CertThumb](#VB_x509CertThumb)` | | [`X509_CheckCertInCRL`](#X509_CheckCertInCRL) | [X509.CheckCertInCRL Method](#M_X509_CheckCertInCRL) | | | [`X509_GetCertCountInP7Chain`](#X509_GetCertCountInP7Chain) | [X509.GetCertCountInP7Chain Method](#M_X509_GetCertCountInP7Chain) | | | [`X509_GetCertFromP7Chain`](#X509_GetCertFromP7Chain) | [X509.GetCertFromP7Chain Method](#M_X509_GetCertFromP7Chain) | | | [`X509_GetCertFromPFX`](#X509_GetCertFromPFX) | [X509.GetCertFromPFX Method](#M_X509_GetCertFromPFX) [X509.GetP7ChainFromPFX Method](#M_X509_GetP7ChainFromPFX) | | | [`X509_HashIssuerAndSN`](#X509_HashIssuerAndSN) | [X509.HashIssuerAndSN Method](#M_X509_HashIssuerAndSN) | `[x509HashIssuerAndSN](#VB_x509HashIssuerAndSN)` | | [`X509_KeyUsageFlags`](#X509_KeyUsageFlags) | [X509.KeyUsageFlags Method](#M_X509_KeyUsageFlags) | | | [`X509_MakeCert`](#X509_MakeCert) | [X509.MakeCert Method](#M_X509_MakeCert) | | | [`X509_MakeCertSelf`](#X509_MakeCertSelf) | [X509.MakeCertSelf Method](#M_X509_MakeCertSelf) | | | [`X509_MakeCRL`](#X509_MakeCRL) | [X509.MakeCRL Method](#M_X509_MakeCRL) | | | [`X509_QueryCert`](#X509_QueryCert) | [X509.QueryCert Method](#M_X509_QueryCert) | `[x509QueryCert](#VB_x509QueryCert)` | | [`X509_ReadCertStringFromP7Chain`](#X509_ReadCertStringFromP7Chain) | [X509.ReadCertStringFromP7Chain Method](#M_X509_ReadCertStringFromP7Chain) | `[x509ReadCertStringFromP7Chain](#VB_x509ReadCertStringFromP7Chain)` | | [`X509_ReadCertStringFromPFX`](#X509_ReadCertStringFromPFX) | [X509.ReadCertStringFromPFX Method](#M_X509_ReadCertStringFromPFX) | `[x509ReadCertStringFromPFX](#VB_x509ReadCertStringFromPFX)` | | [`X509_ReadStringFromFile`](#X509_ReadStringFromFile) | [X509.ReadStringFromFile Method](#M_X509_ReadStringFromFile) | `[x509ReadStringFromFile](#VB_x509ReadStringFromFile)` | | [`X509_SaveFileFromString`](#X509_SaveFileFromString) | [X509.SaveFileFromString Method](#M_X509_SaveFileFromString) | | | [`X509_TextDump`](#X509_TextDump) | [X509.TextDump Method](#M_X509_TextDump) | | | [`X509_TextDumpToString`](#X509_TextDumpToString) | [X509.TextDumpToString Method](#M_X509_TextDumpToString) | `[x509TextDumpToString](#VB_x509TextDumpToString)` | | [`X509_ValidatePath`](#X509_ValidatePath) | [X509.ValidatePath Method](#M_X509_ValidatePath) | | | [`X509_VerifyCert`](#X509_VerifyCert) | [X509.VerifyCert Method](#M_X509_VerifyCert) | | | [`XOF_Bytes`](#XOF_Bytes) | [Xof.Bytes Method](#M_Xof_Bytes) | [`xofBytes`](#VB_xofBytes) | [[Contents](#topofpage)] [[Index](#index)] ### .NET Help File The .NET classes and methods have different parameters and return values to the VB6/C functions described above. Full details are provided in [Summary of .NET Classes](#dotnetsummary) below and also in the help file `CryptoSysPKI.NET.chm` available separately. [[Contents](#topofpage)] [[Index](#index)] Summary of .NET Classes ------------------------------------------------- This manual includes the complete information from the .NET Help File plus cross-references to the equivalent VB6/C functions and examples in `VB.NET`. For a summary showing the VB6/C equivalent functions for these .NET methods, see [Cross-reference between Functions and .NET Methods](#xrefdotnet). --- Class index:    [Asn1](#mx_Asn1) | [Cipher](#mx_Cipher) | [Cms](#mx_Cms) | [Cnv](#mx_Cnv) | [Compr](#mx_Compr) | [Ecc](#mx_Ecc) | [General](#mx_General) | [Hash](#mx_Hash) | [Hmac](#mx_Hmac) | [Hpke](#mx_Hpke) | [Kdf](#mx_Kdf) | [Ocsp](#mx_Ocsp) | [Pbe](#mx_Pbe) | [Pem](#mx_Pem) | [Pfx](#mx_Pfx) | [Prf](#mx_Prf) | [Pwd](#mx_Pwd) | [Rng](#mx_Rng) | [Rsa](#mx_Rsa) | [Sig](#mx_Sig) | [Smime](#mx_Smime) | [Tdea](#mx_Tdea) | [Wipe](#mx_Wipe) | [X509](#mx_X509) | [Xof](#mx_Xof) [[Contents](#topofpage)] [[Index](#index)] --- ### Asn1 Class * [Asn1.TextDump Method](#M_Asn1_TextDump) + Dump details of an ASN.1 formatted data file to a text file. * [Asn1.TextDumpToString Method](#M_Asn1_TextDumpToString) + Dump details of ASN.1 formatted data to a string. * [Asn1.Type Method](#M_Asn1_Type) + Describe the type of ASN.1 data. [[Contents](#topofpage)] [[Index](#index)] ### Cipher Class * [Cipher.BlockBytes Method](#M_Cipher_BlockBytes) + Return the block size in bytes for a given cipher algorithm. * [Cipher.Decrypt Method ](#M_Cipher_Decrypt_ByteByteByteCipherAlgorithmMode) (Byte[], Byte[], Byte[], CipherAlgorithm, Mode) + Decrypt data block in byte array. * [Cipher.Decrypt Method ](#M_Cipher_Decrypt_ByteByteByteCipherAlgorithmModePaddingCipher_Opts) (Byte[], Byte[], Byte[], CipherAlgorithm, Mode, Padding, Cipher.Opts) + Decrypt data in a byte array using the specified block cipher algorithm, mode and padding. * [Cipher.Decrypt Method ](#M_Cipher_Decrypt_StringStringStringCipherAlgorithmMode) (String, String, String, CipherAlgorithm, Mode) + Decrypt data block as hex-encoded string. * [Cipher.Decrypt Method ](#M_Cipher_Decrypt_StringStringStringCipherAlgorithmModePaddingCipher_Opts) (String, String, String, CipherAlgorithm, Mode, Padding, Cipher.Opts) + Decrypt hex-encoded data using specified block cipher algorithm, mode and padding. * [Cipher.DecryptAEAD Method ](#M_Cipher_DecryptAEAD_ByteByteByteAeadAlgorithm) (Byte[], Byte[], Byte[], AeadAlgorithm) + Decrypt data using the AES-GCM authenticated encryption algorithm. * [Cipher.DecryptAEAD Method ](#M_Cipher_DecryptAEAD_ByteByteByteByteAeadAlgorithmCipher_Opts) (Byte[], Byte[], Byte[], Byte[], AeadAlgorithm, Cipher.Opts) + Decrypt data using the AES-GCM authenticated encryption algorithm with AAD and options. * [Cipher.Encrypt Method ](#M_Cipher_Encrypt_ByteByteByteCipherAlgorithmMode) (Byte[], Byte[], Byte[], CipherAlgorithm, Mode) + Encrypt data block in byte array. * [Cipher.Encrypt Method ](#M_Cipher_Encrypt_ByteByteByteCipherAlgorithmModePaddingCipher_Opts) (Byte[], Byte[], Byte[], CipherAlgorithm, Mode, Padding, Cipher.Opts) + Encrypt data in a byte array using the specified block cipher algorithm, mode and padding. * [Cipher.Encrypt Method ](#M_Cipher_Encrypt_StringStringStringCipherAlgorithmMode) (String, String, String, CipherAlgorithm, Mode) + Encrypt data block as hex-encoded string. * [Cipher.Encrypt Method ](#M_Cipher_Encrypt_StringStringStringCipherAlgorithmModePaddingCipher_Opts) (String, String, String, CipherAlgorithm, Mode, Padding, Cipher.Opts) + Encrypt hex-encoded data using specified block cipher algorithm, mode and padding. * [Cipher.EncryptAEAD Method ](#M_Cipher_EncryptAEAD_ByteByteByteAeadAlgorithm) (Byte[], Byte[], Byte[], AeadAlgorithm) + Encrypt data using the AES-GCM authenticated encryption algorithm. * [Cipher.EncryptAEAD Method ](#M_Cipher_EncryptAEAD_ByteByteByteByteAeadAlgorithmCipher_Opts) (Byte[], Byte[], Byte[], Byte[], AeadAlgorithm, Cipher.Opts) + Encrypt data using the AES-GCM authenticated encryption algorithm with AAD and options. * [Cipher.FileDecrypt Method ](#M_Cipher_FileDecrypt_StringStringByteByteCipherAlgorithmModePaddingCipher_Opts) (String, String, Byte[], Byte[], CipherAlgorithm, Mode, Padding, Cipher.Opts) + Decrypt a file. * [Cipher.FileDecrypt Method ](#M_Cipher_FileDecrypt_StringStringStringStringCipherAlgorithmModePaddingCipher_Opts) (String, String, String, String, CipherAlgorithm, Mode, Padding, Cipher.Opts) + Decrypt a file passing key and IV as hex strings. * [Cipher.FileEncrypt Method ](#M_Cipher_FileEncrypt_StringStringByteByteCipherAlgorithmModePaddingCipher_Opts) (String, String, Byte[], Byte[], CipherAlgorithm, Mode, Padding, Cipher.Opts) + Encrypt a file. * [Cipher.FileEncrypt Method ](#M_Cipher_FileEncrypt_StringStringStringStringCipherAlgorithmModePaddingCipher_Opts) (String, String, String, String, CipherAlgorithm, Mode, Padding, Cipher.Opts) + Encrypt a file passing key and IV as hex strings. * [Cipher.KeyBytes Method](#M_Cipher_KeyBytes) + Return the key size in bytes for a given cipher algorithm. * [Cipher.KeyUnwrap Method](#M_Cipher_KeyUnwrap) + Unwrap (decrypt) key material with a key-encryption key. * [Cipher.KeyWrap Method](#M_Cipher_KeyWrap) + Wrap (encrypt) key material with a key-encryption key. * [Cipher.Pad Method ](#M_Cipher_Pad_ByteCipherAlgorithmPadding) (Byte[], CipherAlgorithm, Padding) + Pad byte array to correct length for ECB and CBC encryption. * [Cipher.Pad Method ](#M_Cipher_Pad_StringCipherAlgorithmPadding) (String, CipherAlgorithm, Padding) + Pad hex-encoded string to correct length for ECB and CBC encryption. * [Cipher.Unpad Method ](#M_Cipher_Unpad_ByteCipherAlgorithmPadding) (Byte[], CipherAlgorithm, Padding) + Remove padding from an encryption block. * [Cipher.Unpad Method ](#M_Cipher_Unpad_StringCipherAlgorithmPadding) (String, CipherAlgorithm, Padding) + Remove padding from a hex-encoded encryption block. [[Contents](#topofpage)] [[Index](#index)] ### Cms Class * [Cms.GetSigDataDigest Method](#M_Cms_GetSigDataDigest) + Extract the message digest from a signed-data CMS object file and verify the signature. * [Cms.GetSigHashAlgorithm Method](#M_Cms_GetSigHashAlgorithm) + Find ID of message digest hash algorithm used to make signature. * [Cms.MakeComprData Method](#M_Cms_MakeComprData) + Create a new CMS compressed-data file (.p7z) from an existing input file. * [Cms.MakeDetachedSig Method](#M_Cms_MakeDetachedSig) + Create a "detached signature" CMS signed-data object file from a **message digest** of the content (advanced algorithms). * [Cms.MakeEnvData Method ](#M_Cms_MakeEnvData_StringStringStringCipherAlgorithmCms_EnvDataOptions) (String, String, String, CipherAlgorithm, Cms.EnvDataOptions) + Create a CMS enveloped-data object (default recipient parameters). * [Cms.MakeEnvData Method ](#M_Cms_MakeEnvData_StringStringStringCipherAlgorithmCms_KeyEncrAlgorithmHashAlgorithmCms_EnvDataOptionsKdf_KdfAlgKdf_KeyWrapAlgStringInt32Cms_ContentEncrAlg) (String, String, String, CipherAlgorithm, Cms.KeyEncrAlgorithm, HashAlgorithm, Cms.EnvDataOptions, Kdf.KdfAlg, Kdf.KeyWrapAlg, String, Int32, Cms.ContentEncrAlg) + Create a CMS enveloped-data object (advanced options). * [Cms.MakeEnvDataFromBytes Method](#M_Cms_MakeEnvDataFromBytes) + Create a CMS enveloped-data object from data in a byte array. * [Cms.MakeEnvDataFromString Method ](#M_Cms_MakeEnvDataFromString_StringStringStringCipherAlgorithmCms_EnvDataOptions) (String, String, String, CipherAlgorithm, Cms.EnvDataOptions) + Create a CMS enveloped-data object from an ASCII string (default recipient parameters). * [Cms.MakeEnvDataFromString Method ](#M_Cms_MakeEnvDataFromString_StringStringStringCipherAlgorithmCms_KeyEncrAlgorithmHashAlgorithmCms_EnvDataOptionsKdf_KdfAlgKdf_KeyWrapAlgStringInt32Cms_ContentEncrAlg) (String, String, String, CipherAlgorithm, Cms.KeyEncrAlgorithm, HashAlgorithm, Cms.EnvDataOptions, Kdf.KdfAlg, Kdf.KeyWrapAlg, String, Int32, Cms.ContentEncrAlg) + Create a CMS enveloped-data object from an ASCII string (advanced options). * [Cms.MakeSigData Method ](#M_Cms_MakeSigData_StringStringStringStringCms_SigAlgCms_SigDataOptions) (String, String, String, String, Cms.SigAlg, Cms.SigDataOptions) + Create a CMS object of type SignedData from an input data file (advanced options including RSA-PSS). * [Cms.MakeSigData Method ](#M_Cms_MakeSigData_StringStringStringStringHashAlgorithmCms_SigDataOptions) (String, String, String, String, HashAlgorithm, Cms.SigDataOptions) + Create a CMS object of type SignedData from an input data file using RSASSA-PKCS1V1_5 with options. * [Cms.MakeSigDataFromBytes Method](#M_Cms_MakeSigDataFromBytes) + Create a CMS object of type SignedData from an array of bytes. * [Cms.MakeSigDataFromPseudo Method](#M_Cms_MakeSigDataFromPseudo) + Create a SignedData object from a "pseudo" object. * [Cms.MakeSigDataFromSigValue Method](#M_Cms_MakeSigDataFromSigValue) + Create a CMS object of type SignedData using a pre-computed signature (advanced algorithms). * [Cms.MakeSigDataFromString Method ](#M_Cms_MakeSigDataFromString_StringStringStringStringCms_SigAlgCms_SigDataOptions) (String, String, String, String, Cms.SigAlg, Cms.SigDataOptions) + Create a CMS object of type SignedData from an input string (advanced options including RSA-PSS). * [Cms.MakeSigDataFromString Method ](#M_Cms_MakeSigDataFromString_StringStringStringStringHashAlgorithmCms_SigDataOptions) (String, String, String, String, HashAlgorithm, Cms.SigDataOptions) + Create a CMS object of type SignedData from an input string using RSASSA-PKCS1V1_5 with options. * [Cms.QueryEnvData Method](#M_Cms_QueryEnvData) + Query a CMS enveloped-data object file for selected information. * [Cms.QuerySigData Method](#M_Cms_QuerySigData) + Query a CMS signed-data object for selected information. * [Cms.ReadComprData Method](#M_Cms_ReadComprData) + Read and extract the decompressed contents of a CMS compressed-data file. * [Cms.ReadEnvDataToBytes Method](#M_Cms_ReadEnvDataToBytes) + Read and decrypt a CMS enveloped-data object to a byte array. * [Cms.ReadEnvDataToFile Method](#M_Cms_ReadEnvDataToFile) + Read and decrypt a CMS enveloped-data object to a file. * [Cms.ReadEnvDataToString Method](#M_Cms_ReadEnvDataToString) + Read and decrypt a CMS enveloped-data object to a string. * [Cms.ReadSigDataToBytes Method](#M_Cms_ReadSigDataToBytes) + Read the content from a CMS signed-data object directly into a byte array. * [Cms.ReadSigDataToFile Method](#M_Cms_ReadSigDataToFile) + Read the content from a CMS signed-data object file. * [Cms.ReadSigDataToString Method](#M_Cms_ReadSigDataToString) + Read the content from a CMS signed-data object directly into a string. * [Cms.VerifySigData Method](#M_Cms_VerifySigData) + Verify the signature and content of a signed-data CMS object file. [[Contents](#topofpage)] [[Index](#index)] ### Cnv Class * [Cnv.Base64Filter Method](#M_Cnv_Base64Filter) + Filter non-base64 characters from a string. * [Cnv.Base64FromHex Method](#M_Cnv_Base64FromHex) + Convert hexadecimal-encoded data into base64-encoded data. * [Cnv.ByteEncoding Method](#M_Cnv_ByteEncoding) + Convert encoding of byte array between UTF-8 and Latin-1. * [Cnv.CheckUTF8 Method](#M_Cnv_CheckUTF8) + Check that a byte array contains only valid UTF-8 encoded characters. * [Cnv.CheckUTF8File Method](#M_Cnv_CheckUTF8File) + Check that a file contains only valid UTF-8 encoded characters. * [Cnv.FromBase58 Method](#M_Cnv_FromBase58) + Convert a base58-encoded string to an equivalent array of 8-bit unsigned integers. * [Cnv.FromBase64 Method](#M_Cnv_FromBase64) + Convert a base64-encoded string to an equivalent array of 8-bit unsigned integers. * [Cnv.FromHex Method](#M_Cnv_FromHex) + Convert the specified string representation of a value consisting of hexadecimal (base 16) digits to an equivalent array of 8-bit unsigned integers. * [Cnv.HexFilter Method](#M_Cnv_HexFilter) + Filter non-hexadecimal characters from a string. * [Cnv.HexFromBase64 Method](#M_Cnv_HexFromBase64) + Convert base64-encoded data into hexadecimal-encoded data. * [Cnv.NumFromBytes Method](#M_Cnv_NumFromBytes) + Convert the leftmost four bytes of an array to an unsigned 32-bit integer. * [Cnv.NumToBytes Method](#M_Cnv_NumToBytes) + Convert a 32-bit integer to an array of 4 bytes. * [Cnv.ReverseBytes Method](#M_Cnv_ReverseBytes) + Reverse the order of a byte array. * [Cnv.ShortPathName Method](#M_Cnv_ShortPathName) + Retrieve the Windows short path form of the specified path. * [Cnv.StringFromBase64 Method](#M_Cnv_StringFromBase64) + Convert a base64-encoded string into a text string. * [Cnv.StringFromHex Method](#M_Cnv_StringFromHex) + Convert a hexadecimal-encoded string into a text string. * [Cnv.ToBase58 Method](#M_Cnv_ToBase58) + Convert 8-bit binary data to equivalent base58-encoded string format. * [Cnv.ToBase64 Method ](#M_Cnv_ToBase64_Byte) (Byte[]) + Convert 8-bit binary data to equivalent base64-encoded string format. * [Cnv.ToBase64 Method ](#M_Cnv_ToBase64_String) (String) + Convert a string of ANSI characters to equivalent base64-encoded string format. * [Cnv.ToHex Method ](#M_Cnv_ToHex_Byte) (Byte[]) + Convert 8-bit binary data to equivalent hexadecimal string format. * [Cnv.ToHex Method ](#M_Cnv_ToHex_String) (String) + Converts a string of ANSI characters to equivalent hexadecimal string format [[Contents](#topofpage)] [[Index](#index)] ### Compr Class * [Compr.Compress Method](#M_Compr_Compress) + Compress data using zlib compression. * [Compr.Uncompress Method](#M_Compr_Uncompress) + Uncompress data using zlib compression. [[Contents](#topofpage)] [[Index](#index)] ### Ecc Class * [Ecc.DHSharedSecret Method](#M_Ecc_DHSharedSecret) + Compute EC Diffie-Hellman (ECDH) shared secret. * [Ecc.KeyHashCode Method](#M_Ecc_KeyHashCode) + Compute the hash code of an "internal" ECC public or private key string. * [Ecc.MakeKeys Method](#M_Ecc_MakeKeys) + Generate an EC public/private key pair and save as two key files. * [Ecc.PublicKeyFromPrivate Method](#M_Ecc_PublicKeyFromPrivate) + Convert an internal EC private key string into an internal EC public key string. * [Ecc.QueryKey Method](#M_Ecc_QueryKey) + Query an EC key string for selected information. * [Ecc.ReadKeyByCurve Method](#M_Ecc_ReadKeyByCurve) + Read an EC key from its hexadecimal representation with options for safe curves. * [Ecc.ReadPrivateKey Method](#M_Ecc_ReadPrivateKey) + Read from a file or string containing an EC private key into an "internal" private key string. * [Ecc.ReadPublicKey Method](#M_Ecc_ReadPublicKey) + Read from a file or string containing an EC public key into an "internal" public key string. * [Ecc.SaveEncKey Method](#M_Ecc_SaveEncKey) + Save an internal EC private key string to an encrypted private key file. * [Ecc.SaveKey Method](#M_Ecc_SaveKey) + Save an internal EC key string (public or private) to an unencrypted key file. [[Contents](#topofpage)] [[Index](#index)] ### General Class * [General.CompileTime Method](#M_General_CompileTime) + Return date and time the core CryptoSys PKI DLL was last compiled. * [General.ErrorCode Method](#M_General_ErrorCode) + Return the error code of the *first* error that occurred when calling the last function. * [General.ErrorLookup Method](#M_General_ErrorLookup) + Return a description of an error code. * [General.FormatErrorMessage Method](#M_General_FormatErrorMessage) + Return an error message string for the last error. * [General.LastError Method](#M_General_LastError) + Retrieve the last error message set by the toolkit. * [General.LicenceType Method](#M_General_LicenceType) + Return licence type. * [General.ModuleInfo Method](#M_General_ModuleInfo) + Get additional information about the core DLL module. * [General.ModuleName Method](#M_General_ModuleName) + Return full path name of core CryptoSys PKI DLL module. * [General.NetVersion Method](#M_General_NetVersion) + Return the version of this .NET module. * [General.Platform Method](#M_General_Platform) + Return the platform the core DLL was compiled for. * [General.PowerUpTests Method](#M_General_PowerUpTests) + Perform FIPS-140-2 start-up tests. * [General.Version Method](#M_General_Version) + Return the release version of the core CryptoSys PKI DLL as an integer value. [[Contents](#topofpage)] [[Index](#index)] ### Hash Class * [Hash.BytesFromBytes Method](#M_Hash_BytesFromBytes) + Create hash digest in byte format of byte input. * [Hash.BytesFromFile Method](#M_Hash_BytesFromFile) + Create hash digest of a binary file. * [Hash.Double Method](#M_Hash_Double) + Create double hash, i.e. hash of hash, in byte format of byte input. * [Hash.HexFromBytes Method](#M_Hash_HexFromBytes) + Create hash digest in hex format of byte input. * [Hash.HexFromFile Method](#M_Hash_HexFromFile) + Create hash digest in hex format of a binary file. * [Hash.HexFromHex Method](#M_Hash_HexFromHex) + Create hash digest in hex format of hex-encoded input. * [Hash.HexFromString Method](#M_Hash_HexFromString) + Create hash digest in hex format of string input. * [Hash.HexFromTextFile Method](#M_Hash_HexFromTextFile) + Create hash digest in hex format of a text file, treating CR-LF (0x13, 0x10) pairs as a single LF (0x10). * [Hash.Length Method](#M_Hash_Length) + Return length of message digest output in bytes. [[Contents](#topofpage)] [[Index](#index)] ### Hmac Class * [Hmac.BytesFromBytes Method](#M_Hmac_BytesFromBytes) + Create a keyed-hash HMAC in byte format from byte input. * [Hmac.HexFromBytes Method](#M_Hmac_HexFromBytes) + Create a keyed-hash HMAC in hex-encoded format from byte input. * [Hmac.HexFromHex Method](#M_Hmac_HexFromHex) + Create a keyed-hash HMAC in hex-encoded format from hex-encoded input. [[Contents](#topofpage)] [[Index](#index)] ### Hpke Class * [Hpke.DerivePrivateKey Method](#M_Hpke_DerivePrivateKey) + Derive an EC private key in a deterministic manner from input keying material using the DeriveKeyPair algorithm in RFC9180. * [Hpke.LabeledExpand Method](#M_Hpke_LabeledExpand) + Compute the output of the LabeledExpand function as defined in RFC9180. * [Hpke.LabeledExtract Method](#M_Hpke_LabeledExtract) + Compute the output of the LabeledExtract function as defined in RFC9180. [[Contents](#topofpage)] [[Index](#index)] ### Kdf Class * [Kdf.Bytes Method](#M_Kdf_Bytes) + Generate a key-encryption key (KEK) from input keying material (IKM) using a key derivation function (KDF). * [Kdf.ForCms Method](#M_Kdf_ForCms) + Generate a key-encryption key (KEK) for ECDH key exchange in a CMS EnvelopedData object. [[Contents](#topofpage)] [[Index](#index)] ### Ocsp Class * [Ocsp.MakeRequest Method](#M_Ocsp_MakeRequest) + Create an Online Certification Status Protocol (OCSP) request as a base64 string. * [Ocsp.ReadResponse Method](#M_Ocsp_ReadResponse) + Read a response to an Online Certification Status Protocol (OCSP) request and outputs the main results in text form. [[Contents](#topofpage)] [[Index](#index)] ### Pbe Class * [Pbe.Kdf2 Method ](#M_Pbe_Kdf2_Int32ByteByteInt32HashAlgorithm) (Int32, Byte[], Byte[], Int32, HashAlgorithm) + Derive a key of any length from a password using the PBKDF2 algorithm from PKCS #5 v2.1. * [Pbe.Kdf2 Method ](#M_Pbe_Kdf2_Int32StringStringInt32HashAlgorithm) (Int32, String, String, Int32, HashAlgorithm) + Derive a key in hex format of any length from a password with the salt in hex format. * [Pbe.Scrypt Method ](#M_Pbe_Scrypt_Int32ByteByteInt32Int32Int32) (Int32, Byte[], Byte[], Int32, Int32, Int32) + Derives a key of any length from a password using the SCRYPT algorithm. * [Pbe.Scrypt Method ](#M_Pbe_Scrypt_Int32StringStringInt32Int32Int32) (Int32, String, String, Int32, Int32, Int32) + Derives a key in hex format from a password with the salt in hex format [[Contents](#topofpage)] [[Index](#index)] ### Pem Class * [Pem.FileFromBinFile Method](#M_Pem_FileFromBinFile) + Create a PEM file from a binary file with option for line endings. * [Pem.FileToBinFile Method](#M_Pem_FileToBinFile) + Convert the contents of a PEM file into a binary file. [[Contents](#topofpage)] [[Index](#index)] ### Pfx Class * [Pfx.MakeFile Method](#M_Pfx_MakeFile) + Create a PFX (PKCS-12) file from an X.509 certificate and (optional) encrypted private key file with advanced options. * [Pfx.SignatureIsValid Method](#M_Pfx_SignatureIsValid) + Verify the MacData signature in a PKCS-12 file. [[Contents](#topofpage)] [[Index](#index)] ### Prf Class * [Prf.Bytes Method](#M_Prf_Bytes) + Generate output bytes using a pseudorandom function (PRF). [[Contents](#topofpage)] [[Index](#index)] ### Pwd Class * [Pwd.Prompt Method](#M_Pwd_Prompt) + Open a dialog box to receive a password with user-supplied prompt. [[Contents](#topofpage)] [[Index](#index)] ### Rng Class * [Rng.Bytes Method ](#M_Rng_Bytes_Int32) (Int32) + Generate an array of random bytes. * [Rng.Bytes Method ](#M_Rng_Bytes_Int32Byte) (Int32, Byte[]) + Generate an array of random bytes with user-supplied entropy. * [Rng.Bytes Method ](#M_Rng_Bytes_Int32String) (Int32, String) + Generate an array of random bytes with user-supplied entropy. * [Rng.BytesWithPrompt Method ](#M_Rng_BytesWithPrompt_Int32Rng_Strength) (Int32, Rng.Strength) + Generate an array of random bytes with a prompt for random keyboard input. * [Rng.BytesWithPrompt Method ](#M_Rng_BytesWithPrompt_Int32StringRng_Strength) (Int32, String, Rng.Strength) + Generate an array of random bytes with a prompt for random keyboard input. * [Rng.Guid Method](#M_Rng_Guid) + Generate a random 36-character Global Unique IDentifier (GUID) string according to [RFC4122]. * [Rng.Initialize Method](#M_Rng_Initialize) + Initialize the RNG generator with a seed file. * [Rng.InitializeEx Method](#M_Rng_InitializeEx) + Query and initialize the RNG generator using Intel(R) DRNG, if available. * [Rng.MakeSeedFile Method](#M_Rng_MakeSeedFile) + Create a new seed file suitable for use with Rng.Initialize. * [Rng.Number Method](#M_Rng_Number) + Generate a random number (integer) in a given range. * [Rng.Octet Method](#M_Rng_Octet) + Generate a single random octet (byte). * [Rng.Test Method](#M_Rng_Test) + Carry out a NIST SP800-90 health check and FIPS140-2 statistical tests on the random number generator. * [Rng.TestDrbgvs Method](#M_Rng_TestDrbgvs) + Test the RNG for conformance to NIST SP800-90A using the relevant test specified in DRBGVS. * [Rng.UpdateSeedFile Method](#M_Rng_UpdateSeedFile) + Update the RNG seed file. [[Contents](#topofpage)] [[Index](#index)] ### Rsa Class * [Rsa.CheckKey Method ](#M_Rsa_CheckKey_String) (String) + Check the validity of an "internal" RSA public or private key. * [Rsa.CheckKey Method ](#M_Rsa_CheckKey_StringBuilder) (StringBuilder) + Check the validity of an "internal" RSA public or private key. * [Rsa.DecodeDigestForSignature Method](#M_Rsa_DecodeDigestForSignature) + Decode an encoded message for signature. * [Rsa.DecodeMsgForEncryption Method](#M_Rsa_DecodeMsgForEncryption) + Decode a message for encryption. * [Rsa.DecodeMsgIso9796 Method](#M_Rsa_DecodeMsgIso9796) + Decode a message padded using ISO/IEC 9796-1 formatting. * [Rsa.Decrypt Method](#M_Rsa_Decrypt) + Decrypt a message encrypted using an RSA encryption scheme. * [Rsa.EncodeDigestForSignature Method](#M_Rsa_EncodeDigestForSignature) + Encode a message digest for signature. * [Rsa.EncodeMsgForEncryption Method](#M_Rsa_EncodeMsgForEncryption) + Encode a message for encryption. * [Rsa.EncodeMsgForSignature Method](#M_Rsa_EncodeMsgForSignature) + Encode a message for signature. * [Rsa.EncodeMsgIso9796 Method](#M_Rsa_EncodeMsgIso9796) + Encode a message using ISO/IEC 9796-1 formatting. * [Rsa.Encrypt Method](#M_Rsa_Encrypt) + Encrypt a short message using RSA encryption. * [Rsa.FromXMLString Method ](#M_Rsa_FromXMLString_String) (String) + Create an RSA key string in internal format from an XML string. * [Rsa.FromXMLString Method ](#M_Rsa_FromXMLString_StringRsa_XmlOptions) (String, Rsa.XmlOptions) + Create an RSA key string in internal format from an XML string with options. * [Rsa.FromXMLString Method ](#M_Rsa_FromXMLString_StringBoolean) (String, Boolean) + Create an RSA key string in internal format from an XML string with flag to exclude private key details. * [Rsa.GetPrivateKeyFromPFX Method](#M_Rsa_GetPrivateKeyFromPFX) + Extract an encrypted private key from a PKCS-12 PKCS8ShroudedKeyBag, saving the output directly as a new file. * [Rsa.GetPublicKeyFromCert Method](#M_Rsa_GetPublicKeyFromCert) + Read public key from X.509 certificate into internal string format. * [Rsa.KeyBits Method ](#M_Rsa_KeyBits_String) (String) + Return number of significant bits in RSA key modulus. * [Rsa.KeyBits Method ](#M_Rsa_KeyBits_StringBuilder) (StringBuilder) + Return number of significant bits in RSA key modulus. * [Rsa.KeyBytes Method ](#M_Rsa_KeyBytes_String) (String) + Return number of bytes (octets) in RSA key modulus. * [Rsa.KeyBytes Method ](#M_Rsa_KeyBytes_StringBuilder) (StringBuilder) + Return number of bytes (octets) in RSA key modulus. * [Rsa.KeyHashCode Method ](#M_Rsa_KeyHashCode_String) (String) + Compute the hash code of an "internal" RSA public or private key string. * [Rsa.KeyHashCode Method ](#M_Rsa_KeyHashCode_StringBuilder) (StringBuilder) + Compute the hash code of an "internal" RSA public or private key string. * [Rsa.KeyMatch Method ](#M_Rsa_KeyMatch_StringString) (String, String) + Verify that a pair of "internal" RSA private and public key strings are matched. * [Rsa.KeyMatch Method ](#M_Rsa_KeyMatch_StringBuilderStringBuilder) (StringBuilder, StringBuilder) + Verify that a pair of "internal" RSA private and public key strings are matched. * [Rsa.KeyValue Method](#M_Rsa_KeyValue) + Extract a base64-encoded RSA key value from internal key string * [Rsa.MakeKeys Method ](#M_Rsa_MakeKeys_StringStringInt32Rsa_PublicExponentInt32StringCipherAlgorithmHashAlgorithmRsa_FormatBoolean) (String, String, Int32, Rsa.PublicExponent, Int32, String, CipherAlgorithm, HashAlgorithm, Rsa.Format, Boolean) + Generate an RSA public/private key pair with extended options for encrypting private key [DEPRECATED]. * [Rsa.MakeKeys Method ](#M_Rsa_MakeKeys_StringStringInt32Rsa_PublicExponentInt32StringRsa_PbeOptionsBooleanByte) (String, String, Int32, Rsa.PublicExponent, Int32, String, Rsa.PbeOptions, Boolean, Byte[]) + Generate an RSA public/private key pair [DEPRECATED]. * [Rsa.MakeKeys Method ](#M_Rsa_MakeKeys_StringStringStringInt32Rsa_PublicExponentRsa_PbeOptionsStringRsa_FormatBoolean) (String, String, String, Int32, Rsa.PublicExponent, Rsa.PbeOptions, String, Rsa.Format, Boolean) + Generate an RSA public/private key pair. * [Rsa.PublicKeyFromPrivate Method](#M_Rsa_PublicKeyFromPrivate) + Convert an internal private key string into a public one. * [Rsa.RawPrivate Method ](#M_Rsa_RawPrivate_ByteString) (Byte[], String) + Carry out RSA transformation using private key. * [Rsa.RawPrivate Method ](#M_Rsa_RawPrivate_ByteStringInt32) (Byte[], String, Int32) + Carry out RSA transformation using private key (with specialist options). * [Rsa.RawPublic Method ](#M_Rsa_RawPublic_ByteString) (Byte[], String) + Carry out RSA transformation using public key. * [Rsa.RawPublic Method ](#M_Rsa_RawPublic_ByteStringInt32) (Byte[], String, Int32) + Carry out RSA transformation using public key (with specialist options). * [Rsa.ReadEncPrivateKey Method](#M_Rsa_ReadEncPrivateKey) + Read encrypted private key file into internal string format. * [Rsa.ReadPrivateKey Method](#M_Rsa_ReadPrivateKey) + Read from a file or string containing a private key into an "internal" private key string. * [Rsa.ReadPrivateKeyFromPFX Method](#M_Rsa_ReadPrivateKeyFromPFX) + Read a private key directly from an encrypted PFX/PKCS-12 file into an "internal" private key string. * [Rsa.ReadPrivateKeyInfo Method](#M_Rsa_ReadPrivateKeyInfo) + Read from an (unencrypted) PKCS-8 private key info file into a private key string. * [Rsa.ReadPublicKey Method](#M_Rsa_ReadPublicKey) + Read from a file or string containing a public key into an "internal" public key string. * [Rsa.SaveEncKey Method](#M_Rsa_SaveEncKey) + Save an internal RSA key string to an encrypted key file. * [Rsa.SaveEncPrivateKey Method ](#M_Rsa_SaveEncPrivateKey_StringStringInt32StringCipherAlgorithmHashAlgorithmRsa_Format) (String, String, Int32, String, CipherAlgorithm, HashAlgorithm, Rsa.Format) + Save a private key string to a PKCS-8 EncryptedPrivateKeyInfo file using PBES2 algorithm [DEPRECATED]. * [Rsa.SaveEncPrivateKey Method ](#M_Rsa_SaveEncPrivateKey_StringStringInt32StringRsa_PbeOptionsRsa_Format) (String, String, Int32, String, Rsa.PbeOptions, Rsa.Format) + Save a private key string to a PKCS-8 EncryptedPrivateKeyInfo file [DEPRECATED]. * [Rsa.SavePrivateKeyInfo Method](#M_Rsa_SavePrivateKeyInfo) + Save a private key string to an (unencrypted) PKCS-8 private key info file. * [Rsa.SavePublicKey Method](#M_Rsa_SavePublicKey) + Save a public key string to PKCS-1 public key file. * [Rsa.ToXMLString Method ](#M_Rsa_ToXMLString_StringRsa_XmlOptions) (String, Rsa.XmlOptions) + Create an XML string representation of an RSA internal key string. * [Rsa.ToXMLString Method ](#M_Rsa_ToXMLString_StringStringRsa_XmlOptions) (String, String, Rsa.XmlOptions) + Create an XML string representation of an RSA internal key string with option to add a namespace prefix. [[Contents](#topofpage)] [[Index](#index)] ### Sig Class * [Sig.GetHashAlgFromSigAlg Method](#M_Sig_GetHashAlgFromSigAlg) + Get the hash algorithm used in the signature algorithm. * [Sig.SignData Method](#M_Sig_SignData) + Compute a signature value over data in a byte array. * [Sig.SignDigest Method](#M_Sig_SignDigest) + Compute a signature value over a message digest value. * [Sig.SignFile Method](#M_Sig_SignFile) + Compute a signature value over binary data in a file. * [Sig.VerifyData Method](#M_Sig_VerifyData) + Verify a signature value over data in a byte array. * [Sig.VerifyDigest Method](#M_Sig_VerifyDigest) + Verify a signature value over a message digest value of data. * [Sig.VerifyFile Method](#M_Sig_VerifyFile) + Verify a signature value over data in a file. [[Contents](#topofpage)] [[Index](#index)] ### Smime Class * [Smime.Extract Method](#M_Smime_Extract) + Extract the body from an S/MIME entity. * [Smime.Query Method](#M_Smime_Query) + Query an S/MIME entity for selected information. * [Smime.Wrap Method](#M_Smime_Wrap) + Wrap a CMS object in an S/MIME entity. [[Contents](#topofpage)] [[Index](#index)] ### Tdea Class * [Tdea.Decrypt Method ](#M_Tdea_Decrypt_ByteByteModeByte) (Byte[], Byte[], Mode, Byte[]) + Decrypt data in byte array. * [Tdea.Decrypt Method ](#M_Tdea_Decrypt_StringStringModeString) (String, String, Mode, String) + Decrypt hex-encoded data string. * [Tdea.Decrypt Method ](#M_Tdea_Decrypt_StringStringModeStringEncodingBase) (String, String, Mode, String, EncodingBase) + Decrypt encoded data string. * [Tdea.Encrypt Method ](#M_Tdea_Encrypt_ByteByteModeByte) (Byte[], Byte[], Mode, Byte[]) + Encrypt data in byte array. * [Tdea.Encrypt Method ](#M_Tdea_Encrypt_StringStringModeString) (String, String, Mode, String) + Encrypt hex-encoded data string. * [Tdea.Encrypt Method ](#M_Tdea_Encrypt_StringStringModeStringEncodingBase) (String, String, Mode, String, EncodingBase) + Encrypt encoded data string. * [Tdea.FileDecrypt Method ](#M_Tdea_FileDecrypt_StringStringByteModeByte) (String, String, Byte[], Mode, Byte[]) + Decrypt a file. * [Tdea.FileDecrypt Method ](#M_Tdea_FileDecrypt_StringStringStringModeString) (String, String, String, Mode, String) + Decrypt a file passing key and IV as hex strings. * [Tdea.FileEncrypt Method ](#M_Tdea_FileEncrypt_StringStringByteModeByte) (String, String, Byte[], Mode, Byte[]) + Encrypt a file. * [Tdea.FileEncrypt Method ](#M_Tdea_FileEncrypt_StringStringStringModeString) (String, String, String, Mode, String) + Encrypt a file passing key and IV as hex strings. [[Contents](#topofpage)] [[Index](#index)] ### Wipe Class * [Wipe.Data Method](#M_Wipe_Data) + Zeroise data in memory. * [Wipe.File Method](#M_Wipe_File) + Securely wipe and delete a file with options. * [Wipe.String Method](#M_Wipe_String) + Zeroise a StringBuilder. [[Contents](#topofpage)] [[Index](#index)] ### X509 Class * [X509.CertExpiresOn Method](#M_X509_CertExpiresOn) + Return date and time certificate expires. * [X509.CertIssuedOn Method](#M_X509_CertIssuedOn) + Return date and time certificate was issued. * [X509.CertIssuerName Method](#M_X509_CertIssuerName) + Get the issuer name of an X.509 certificate. * [X509.CertIsValidNow Method](#M_X509_CertIsValidNow) + Verify that an X.509 certificate is currently valid as per system clock. * [X509.CertRequest Method](#M_X509_CertRequest) + Create a PKCS #10 certificate signing request (CSR). * [X509.CertSerialNumber Method](#M_X509_CertSerialNumber) + Return serial number in hex format. * [X509.CertSubjectName Method](#M_X509_CertSubjectName) + Get the subject name of an X.509 certificate. * [X509.CertThumb Method](#M_X509_CertThumb) + Calculate the thumbprint (message digest hash) of an X.509 certificate. * [X509.CheckCertInCRL Method](#M_X509_CheckCertInCRL) + Check whether an X.509 certificate has been revoked in a Certificate Revocation List (CRL). * [X509.GetCertCountInP7Chain Method](#M_X509_GetCertCountInP7Chain) + Return number of certificates in a PKCS-7 "certs-only" certificate chain file. * [X509.GetCertFromP7Chain Method](#M_X509_GetCertFromP7Chain) + Extract an X.509 certificate from a PKCS-7 "certs-only" certificate chain file, saving the output directly as a new file. * [X509.GetCertFromPFX Method](#M_X509_GetCertFromPFX) + Extract an X.509 certificate from a PKCS-12 PFX/.p12 file, saving the output directly as a new file. * [X509.GetP7ChainFromPFX Method](#M_X509_GetP7ChainFromPFX) + Extract all X.509 certificates from a PKCS-12 PFX/.p12 file, saving the output directly as a new PKCS-7 "certs-only" certificate chain file. * [X509.HashIssuerAndSN Method](#M_X509_HashIssuerAndSN) + Create a message digest of the Issuer's name and the cert serial number. * [X509.KeyUsageFlags Method](#M_X509_KeyUsageFlags) + Returns a bitfield containing the keyUsage flags. * [X509.MakeCert Method](#M_X509_MakeCert) + Create a new X.509 certificate using subject's public key and issuer's private key files with signature options. * [X509.MakeCertSelf Method](#M_X509_MakeCertSelf) + Create a self-signed X.509 certificate with signature options. * [X509.MakeCRL Method](#M_X509_MakeCRL) + Create an X.509 Certificate Revocation List (CRL). * [X509.QueryCert Method](#M_X509_QueryCert) + Query an X.509 certificate file for selected information. * [X509.ReadCertStringFromP7Chain Method](#M_X509_ReadCertStringFromP7Chain) + Read an X.509 certificate into a base64 string from PKCS-7 "certs-only" data. * [X509.ReadCertStringFromPFX Method](#M_X509_ReadCertStringFromPFX) + Read an X.509 certificate into a base64 string from PKCS-12 PFX/.p12 data. * [X509.ReadStringFromFile Method](#M_X509_ReadStringFromFile) + Create a base64 string representation of a X.509 certificate file. * [X509.SaveFileFromString Method](#M_X509_SaveFileFromString) + Create a new X.509 certificate file from a base64 string representation. * [X509.TextDump Method](#M_X509_TextDump) + Dump details of an X.509 certificate or a X.509 certificate revocation list (CRL) or a PKCS-10 certificate signing request (CSR) to a text file. * [X509.TextDumpToString Method](#M_X509_TextDumpToString) + Dump details of an X.509 certificate or a X.509 certificate revocation list (CRL) or a PKCS-10 certificate signing request (CSR) to a string. * [X509.ValidatePath Method](#M_X509_ValidatePath) + Validate a certificate path. * [X509.VerifyCert Method](#M_X509_VerifyCert) + Verify that an X.509 certificate has been signed by its issuer. [[Contents](#topofpage)] [[Index](#index)] ### Xof Class * [Xof.Bytes Method](#M_Xof_Bytes) + Generate bytes using an eXtendable-Output Function (XOF). [[Contents](#topofpage)] [[Index](#index)] List of .Net Methods ------------------------------------------- Class index:    [Asn1](#mx_Asn1) | [Cipher](#mx_Cipher) | [Cms](#mx_Cms) | [Cnv](#mx_Cnv) | [Compr](#mx_Compr) | [Ecc](#mx_Ecc) | [General](#mx_General) | [Hash](#mx_Hash) | [Hmac](#mx_Hmac) | [Hpke](#mx_Hpke) | [Kdf](#mx_Kdf) | [Ocsp](#mx_Ocsp) | [Pbe](#mx_Pbe) | [Pem](#mx_Pem) | [Pfx](#mx_Pfx) | [Prf](#mx_Prf) | [Pwd](#mx_Pwd) | [Rng](#mx_Rng) | [Rsa](#mx_Rsa) | [Sig](#mx_Sig) | [Smime](#mx_Smime) | [Tdea](#mx_Tdea) | [Wipe](#mx_Wipe) | [X509](#mx_X509) | [Xof](#mx_Xof) [[Contents](#topofpage)] [[Index](#index)] --- ### Asn1.TextDump Method Dump details of an ASN.1 formatted data file to a text file. #### Syntax [`C#`] ``` public static int TextDump( string outputFile, string fileOrPEMString, Asn1.Options options ) ``` [`VB.NET`] ``` Public Shared Function TextDump ( _ outputFile As String, _ fileOrPEMString As String, _ options As Asn1.Options _ ) As Integer ``` #### Parameters outputFile : Filename of text file to be created fileOrPEMString : Filename of ASN.1 formatted data file to be analyzed (or a string containing its base64 or PEM representation) options : Type: [Asn1.Options](#T_Asn1_Options) Option flags (optional) #### Return Value Zero if successful; otherwise it returns an [error code](#errorcodes) #### See Also VB6/C equivalent: [`ASN1_TextDump`](#ASN1_TextDump) [[Contents](#topofpage)] [[Index](#index)] --- ### Asn1.TextDumpToString Method Dump details of ASN.1 formatted data to a string. #### Syntax [`C#`] ``` public static string TextDumpToString( string fileOrPEMString, Asn1.Options options ) ``` [`VB.NET`] ``` Public Shared Function TextDumpToString ( _ fileOrPEMString As String, _ options As Asn1.Options _ ) As String ``` #### Parameters fileOrPEMString : Filename of ASN.1 formatted data file to be analyzed (or a string containing its base64 or PEM representation) options : Type: [Asn1.Options](#T_Asn1_Options) Option flags: set as zero for defaults. #### Return Value String containing the output. #### Remarks This function creates a temporary file in the system TEMP directory. This file is locked and is automatically deleted after use. #### See Also VB6/C equivalent: [`ASN1_TextDumpToString`](#ASN1_TextDumpToString) [[Contents](#topofpage)] [[Index](#index)] --- ### Asn1.Type Method Describe the type of ASN.1 data. #### Syntax [`C#`] ``` public static string Type( string fileOrPEMString ) ``` [`VB.NET`] ``` Public Shared Function Type ( _ fileOrPEMString As String _ ) As String ``` #### Parameters fileOrPEMString : Filename of ASN.1 formatted data file to be analyzed (or a string containing its base64 or PEM representation) #### Return Value String containing the name of the type of ASN.1 data or the empty string if not found #### See Also VB6/C equivalent: [`ASN1_Type`](#ASN1_Type) [[Contents](#topofpage)] [[Index](#index)] --- ### Cipher.BlockBytes Method Return the block size in bytes for a given cipher algorithm. #### Syntax [`C#`] ``` public static int BlockBytes( CipherAlgorithm alg ) ``` [`VB.NET`] ``` Public Shared Function BlockBytes ( _ alg As CipherAlgorithm _ ) As Integer ``` #### Parameters alg : Type: [CipherAlgorithm](#T_CipherAlgorithm) Cipher algorithm #### Return Value Block size in bytes [[Contents](#topofpage)] [[Index](#index)] --- ### Cipher.Decrypt Method (Byte[], Byte[], Byte[], CipherAlgorithm, Mode) Decrypt data block in byte array. #### Syntax [`C#`] ``` public static byte[] Decrypt( byte[] input, byte[] key, byte[] iv, CipherAlgorithm cipherAlg, Mode mode ) ``` [`VB.NET`] ``` Public Shared Function Decrypt ( _ input As Byte(), _ key As Byte(), _ iv As Byte(), _ cipherAlg As CipherAlgorithm, _ mode As Mode _ ) As Byte() ``` #### Parameters input : Input data to be decrypted key : Key of exact length for block cipher algorithm iv : Initialization Vector (IV) of exactly the block size or null for ECB mode cipherAlg : Type: [CipherAlgorithm](#T_CipherAlgorithm) Cipher algorithm mode : Type: [Mode](#T_Mode) Cipher mode #### Return Value Decrypted data in byte array or empty array on error #### Remarks For ECB and CBC modes, input data length **must** be an exact multiple of the block length. #### See Also VB6/C equivalent: [`CIPHER_Bytes`](#CIPHER_Bytes) [[Contents](#topofpage)] [[Index](#index)] --- ### Cipher.Decrypt Method (Byte[], Byte[], Byte[], CipherAlgorithm, Mode, Padding, Cipher.Opts) Decrypt data in a byte array using the specified block cipher algorithm, mode and padding. #### Syntax [`C#`] ``` public static byte[] Decrypt( byte[] input, byte[] key, byte[] iv, CipherAlgorithm cipherAlg, Mode mode, Padding pad, Cipher.Opts opts ) ``` [`VB.NET`] ``` Public Shared Function Decrypt ( _ input As Byte(), _ key As Byte(), _ iv As Byte(), _ cipherAlg As CipherAlgorithm, _ mode As Mode, _ pad As Padding, _ opts As Cipher.Opts _ ) As Byte() ``` #### Parameters input : Input data to be decrypted key : Key of exact length for block cipher algorithm iv : Initialization Vector (IV) of exactly the block size, or null for ECB mode or if IV is prefixed. cipherAlg : Type: [CipherAlgorithm](#T_CipherAlgorithm) Cipher algorithm mode : Type: [Mode](#T_Mode) Cipher mode pad : Type: [Padding](#T_Padding) Padding method to use opts : Type: [Cipher.Opts](#T_Cipher_Opts) Advanced options. Use Cipher.Opts.PrefixIV to expect the IV to be prepended to the input. #### Return Value Decrypted plaintext in byte array or empty array on error #### Remarks Default padding is Pkcs5 for ECB and CBC mode and NoPad for all other modes. It is an error if the specified padding is not found after decryption. #### See Also VB6/C equivalent: [`CIPHER_DecryptBytes`](#CIPHER_DecryptBytes) [[Contents](#topofpage)] [[Index](#index)] --- ### Cipher.Decrypt Method (String, String, String, CipherAlgorithm, Mode) Decrypt data block as hex-encoded string. #### Syntax [`C#`] ``` public static string Decrypt( string inputHex, string keyHex, string ivHex, CipherAlgorithm cipherAlg, Mode mode ) ``` [`VB.NET`] ``` Public Shared Function Decrypt ( _ inputHex As String, _ keyHex As String, _ ivHex As String, _ cipherAlg As CipherAlgorithm, _ mode As Mode _ ) As String ``` #### Parameters inputHex : Hex-encoded input data keyHex : Hex-encoded key representing exact key length ivHex : Hex-encoded IV representing exact block length or "" for ECB mode cipherAlg : Type: [CipherAlgorithm](#T_CipherAlgorithm) Cipher Algorithm mode : Type: [Mode](#T_Mode) Cipher Mode #### Return Value Decrypted plaintext in hex-encoded string or empty string on error #### Remarks For ECB and CBC modes, input data length **must** represent an exact multiple of the block length. #### See Also VB6/C equivalent: [`CIPHER_Hex`](#CIPHER_Hex) [[Contents](#topofpage)] [[Index](#index)] --- ### Cipher.Decrypt Method (String, String, String, CipherAlgorithm, Mode, Padding, Cipher.Opts) Decrypt hex-encoded data using specified block cipher algorithm, mode and padding. #### Syntax [`C#`] ``` public static string Decrypt( string inputHex, string keyHex, string ivHex, CipherAlgorithm cipherAlg, Mode mode, Padding pad, Cipher.Opts opts ) ``` [`VB.NET`] ``` Public Shared Function Decrypt ( _ inputHex As String, _ keyHex As String, _ ivHex As String, _ cipherAlg As CipherAlgorithm, _ mode As Mode, _ pad As Padding, _ opts As Cipher.Opts _ ) As String ``` #### Parameters inputHex : Hex-encoded input data keyHex : Hex-encoded key representing exact key length ivHex : Hex-encoded IV representing exact block length, or "" for ECB mode or if IV is prefixed. cipherAlg : Type: [CipherAlgorithm](#T_CipherAlgorithm) Cipher Algorithm mode : Type: [Mode](#T_Mode) Cipher Mode pad : Type: [Padding](#T_Padding) Padding method to use opts : Type: [Cipher.Opts](#T_Cipher_Opts) Advanced options. Use Cipher.Opts.PrefixIV to expect the IV to be prepended to the input. #### Return Value Decrypted plaintex in hex-encoded string or empty string on error #### Remarks Input data may be any even number of hex characters, but not zero. Default padding is Pkcs5 for ECB and CBC mode and NoPad for all other modes. #### See Also VB6/C equivalent: [`CIPHER_DecryptHex`](#CIPHER_DecryptHex) [[Contents](#topofpage)] [[Index](#index)] --- ### Cipher.DecryptAEAD Method (Byte[], Byte[], Byte[], AeadAlgorithm) Decrypt data using the AES-GCM authenticated encryption algorithm. #### Syntax [`C#`] ``` public static byte[] DecryptAEAD( byte[] input, byte[] key, byte[] iv, AeadAlgorithm aeadAlg ) ``` [`VB.NET`] ``` Public Shared Function DecryptAEAD ( _ input As Byte(), _ key As Byte(), _ iv As Byte(), _ aeadAlg As AeadAlgorithm _ ) As Byte() ``` #### Parameters input : Input data to be decrypted. key : Key of exact length for algorithm (16, 24 or 32 bytes). iv : Initialization Vector (IV) (aka nonce) exactly 12 bytes long. aeadAlg : Type: [AeadAlgorithm](#T_AeadAlgorithm) Authenticated encryption algorithm. #### Return Value Plaintext in a byte array, or empty array on error (an empty array may also be the correct result - check General.ErrorCode for details). #### Remarks The input *must* include the 16-byte tag appended to the ciphertext. The output will be exactly 16 bytes shorter than the input. In all cases the IV *must* be exactly 12 bytes (96 bits) and the tag *must* be exactly 16 bytes (128 bits). #### See Also VB6/C equivalent: [`CIPHER_DecryptAEAD`](#CIPHER_DecryptAEAD) [[Contents](#topofpage)] [[Index](#index)] --- ### Cipher.DecryptAEAD Method (Byte[], Byte[], Byte[], Byte[], AeadAlgorithm, Cipher.Opts) Decrypt data using the AES-GCM authenticated encryption algorithm with AAD and options. #### Syntax [`C#`] ``` public static byte[] DecryptAEAD( byte[] input, byte[] key, byte[] iv, byte[] aad, AeadAlgorithm aeadAlg, Cipher.Opts opts ) ``` [`VB.NET`] ``` Public Shared Function DecryptAEAD ( _ input As Byte(), _ key As Byte(), _ iv As Byte(), _ aad As Byte(), _ aeadAlg As AeadAlgorithm, _ opts As Cipher.Opts _ ) As Byte() ``` #### Parameters input : Input data to be decrypted. key : Key of exact length for algorithm (16, 24 or 32 bytes). iv : Initialization Vector (IV) (aka nonce) exactly 12 bytes long, if not provided in input. aad : Additional authenticated data (optional) - set as null to ignore. aeadAlg : Type: [AeadAlgorithm](#T_AeadAlgorithm) Authenticated encryption algorithm. opts : Type: [Cipher.Opts](#T_Cipher_Opts) Advanced options. Use Cipher.Opts.PrefixIV to expect the IV to be prepended at the start of the input. #### Return Value Plaintext in a byte array, or empty array on error (an empty array may also be the correct result - check General.ErrorCode for details). #### Remarks The input *must* include the 16-byte tag appended to the ciphertext and may include a 12-byte prefixed IV. The output will either be exactly 16 bytes shorter than the input, or exactly 28 bytes shorter if the Cipher.Opts.PrefixIV option is used. In all cases the IV *must* be exactly 12 bytes (96 bits) and the tag *must* be exactly 16 bytes (128 bits). If additional authentication data (AAD) was provided during encryption then the exact same AAD data must be provided here. #### See Also VB6/C equivalent: [`CIPHER_DecryptAEAD`](#CIPHER_DecryptAEAD) [[Contents](#topofpage)] [[Index](#index)] --- ### Cipher.Encrypt Method (Byte[], Byte[], Byte[], CipherAlgorithm, Mode) Encrypt data block in byte array. #### Syntax [`C#`] ``` public static byte[] Encrypt( byte[] input, byte[] key, byte[] iv, CipherAlgorithm cipherAlg, Mode mode ) ``` [`VB.NET`] ``` Public Shared Function Encrypt ( _ input As Byte(), _ key As Byte(), _ iv As Byte(), _ cipherAlg As CipherAlgorithm, _ mode As Mode _ ) As Byte() ``` #### Parameters input : Input data to be encrypted key : Key of exact length for block cipher algorithm iv : Initialization Vector (IV) of exactly the block size or null for ECB mode cipherAlg : Type: [CipherAlgorithm](#T_CipherAlgorithm) Cipher algorithm mode : Type: [Mode](#T_Mode) Cipher mode #### Return Value Ciphertext in byte array or empty array on error #### Remarks For ECB and CBC modes, input data length **must** be an exact multiple of the block length. #### See Also VB6/C equivalent: [`CIPHER_Bytes`](#CIPHER_Bytes) [[Contents](#topofpage)] [[Index](#index)] --- ### Cipher.Encrypt Method (Byte[], Byte[], Byte[], CipherAlgorithm, Mode, Padding, Cipher.Opts) Encrypt data in a byte array using the specified block cipher algorithm, mode and padding. #### Syntax [`C#`] ``` public static byte[] Encrypt( byte[] input, byte[] key, byte[] iv, CipherAlgorithm cipherAlg, Mode mode, Padding pad, Cipher.Opts opts ) ``` [`VB.NET`] ``` Public Shared Function Encrypt ( _ input As Byte(), _ key As Byte(), _ iv As Byte(), _ cipherAlg As CipherAlgorithm, _ mode As Mode, _ pad As Padding, _ opts As Cipher.Opts _ ) As Byte() ``` #### Parameters input : Input data to be encrypted key : Key of exact length for block cipher algorithm iv : Initialization Vector (IV) of exactly the block size or null for ECB mode. cipherAlg : Type: [CipherAlgorithm](#T_CipherAlgorithm) Cipher algorithm mode : Type: [Mode](#T_Mode) Cipher mode pad : Type: [Padding](#T_Padding) Padding method to use opts : Type: [Cipher.Opts](#T_Cipher_Opts) Advanced options. Use Cipher.Opts.PrefixIV to prepend the IV to the output. #### Return Value Ciphertext in byte array or empty array on error #### Remarks Default padding is Pkcs5 for ECB and CBC mode and NoPad for all other modes. #### See Also VB6/C equivalent: [`CIPHER_EncryptBytes`](#CIPHER_EncryptBytes) [[Contents](#topofpage)] [[Index](#index)] --- ### Cipher.Encrypt Method (String, String, String, CipherAlgorithm, Mode) Encrypt data block as hex-encoded string. #### Syntax [`C#`] ``` public static string Encrypt( string inputHex, string keyHex, string ivHex, CipherAlgorithm cipherAlg, Mode mode ) ``` [`VB.NET`] ``` Public Shared Function Encrypt ( _ inputHex As String, _ keyHex As String, _ ivHex As String, _ cipherAlg As CipherAlgorithm, _ mode As Mode _ ) As String ``` #### Parameters inputHex : Hex-encoded input data keyHex : Hex-encoded key representing exact key length ivHex : Hex-encoded IV representing exact block length or "" for ECB mode cipherAlg : Type: [CipherAlgorithm](#T_CipherAlgorithm) Cipher algorithm mode : Type: [Mode](#T_Mode) Cipher mode #### Return Value Ciphertext in hex-encoded string or empty string on error #### Remarks For ECB and CBC modes, input data length **must** be an exact multiple of the block length. #### See Also VB6/C equivalent: [`CIPHER_Hex`](#CIPHER_Hex) [[Contents](#topofpage)] [[Index](#index)] --- ### Cipher.Encrypt Method (String, String, String, CipherAlgorithm, Mode, Padding, Cipher.Opts) Encrypt hex-encoded data using specified block cipher algorithm, mode and padding. #### Syntax [`C#`] ``` public static string Encrypt( string inputHex, string keyHex, string ivHex, CipherAlgorithm cipherAlg, Mode mode, Padding pad, Cipher.Opts opts ) ``` [`VB.NET`] ``` Public Shared Function Encrypt ( _ inputHex As String, _ keyHex As String, _ ivHex As String, _ cipherAlg As CipherAlgorithm, _ mode As Mode, _ pad As Padding, _ opts As Cipher.Opts _ ) As String ``` #### Parameters inputHex : Hex-encoded input data keyHex : Hex-encoded key representing exact key length ivHex : Hex-encoded IV representing exact block length or "" for ECB mode cipherAlg : Type: [CipherAlgorithm](#T_CipherAlgorithm) Cipher Algorithm mode : Type: [Mode](#T_Mode) Cipher Mode pad : Type: [Padding](#T_Padding) Padding method to use (optional) opts : Type: [Cipher.Opts](#T_Cipher_Opts) Advanced options. Use Cipher.Opts.PrefixIV to prepend the IV to the output. #### Return Value Encrypted ciphertext in hex-encoded string or empty string on error #### Remarks Input data may be any even number of hex characters, but not zero. Default padding is Pkcs5 for ECB and CBC mode and NoPad for all other modes. #### See Also VB6/C equivalent: [`CIPHER_EncryptHex`](#CIPHER_EncryptHex) [[Contents](#topofpage)] [[Index](#index)] --- ### Cipher.EncryptAEAD Method (Byte[], Byte[], Byte[], AeadAlgorithm) Encrypt data using the AES-GCM authenticated encryption algorithm. #### Syntax [`C#`] ``` public static byte[] EncryptAEAD( byte[] input, byte[] key, byte[] iv, AeadAlgorithm aeadAlg ) ``` [`VB.NET`] ``` Public Shared Function EncryptAEAD ( _ input As Byte(), _ key As Byte(), _ iv As Byte(), _ aeadAlg As AeadAlgorithm _ ) As Byte() ``` #### Parameters input : Input data to be encrypted. key : Key of exact length for algorithm (16, 24 or 32 bytes). iv : Initialization Vector (IV) (aka nonce) exactly 12 bytes long. aeadAlg : Type: [AeadAlgorithm](#T_AeadAlgorithm) Authenticated encryption algorithm. #### Return Value Ciphertext with tag appended in a byte array, or empty array on error. #### Remarks The output will be exactly 16 bytes longer than the input. #### See Also VB6/C equivalent: [`CIPHER_EncryptAEAD`](#CIPHER_EncryptAEAD) [[Contents](#topofpage)] [[Index](#index)] --- ### Cipher.EncryptAEAD Method (Byte[], Byte[], Byte[], Byte[], AeadAlgorithm, Cipher.Opts) Encrypt data using the AES-GCM authenticated encryption algorithm with AAD and options. #### Syntax [`C#`] ``` public static byte[] EncryptAEAD( byte[] input, byte[] key, byte[] iv, byte[] aad, AeadAlgorithm aeadAlg, Cipher.Opts opts ) ``` [`VB.NET`] ``` Public Shared Function EncryptAEAD ( _ input As Byte(), _ key As Byte(), _ iv As Byte(), _ aad As Byte(), _ aeadAlg As AeadAlgorithm, _ opts As Cipher.Opts _ ) As Byte() ``` #### Parameters input : Input data to be encrypted. key : Key of exact length for algorithm (16, 24 or 32 bytes). iv : Initialization Vector (IV) (aka nonce) exactly 12 bytes long. aad : Additional authenticated data (optional) - set as null to ignore. aeadAlg : Type: [AeadAlgorithm](#T_AeadAlgorithm) Authenticated encryption algorithm. opts : Type: [Cipher.Opts](#T_Cipher_Opts) Advanced options. Use Cipher.Opts.PrefixIV to prepend the 12-byte IV to the output #### Return Value Ciphertext with tag appended in a byte array, or empty array on error. #### Remarks The output will either be exactly 16 bytes longer than the input, or exactly 28 bytes longer if Cipher.Opts.PrefixIV is used. #### See Also VB6/C equivalent: [`CIPHER_EncryptAEAD`](#CIPHER_EncryptAEAD) [[Contents](#topofpage)] [[Index](#index)] --- ### Cipher.FileDecrypt Method (String, String, Byte[], Byte[], CipherAlgorithm, Mode, Padding, Cipher.Opts) Decrypt a file. #### Syntax [`C#`] ``` public static int FileDecrypt( string fileOut, string fileIn, byte[] key, byte[] iv, CipherAlgorithm cipherAlg, Mode mode, Padding pad, Cipher.Opts opts ) ``` [`VB.NET`] ``` Public Shared Function FileDecrypt ( _ fileOut As String, _ fileIn As String, _ key As Byte(), _ iv As Byte(), _ cipherAlg As CipherAlgorithm, _ mode As Mode, _ pad As Padding, _ opts As Cipher.Opts _ ) As Integer ``` #### Parameters fileOut : Name of output file to be created or overwritten fileIn : Name of input file key : Key of of exact length for block cipher algorithm iv : Initialization Vector (IV) of exactly the block size, or null for ECB mode or if IV is prefixed. cipherAlg : Type: [CipherAlgorithm](#T_CipherAlgorithm) Cipher Algorithm mode : Type: [Mode](#T_Mode) Cipher Mode pad : Type: [Padding](#T_Padding) Padding method to use (optional, ECB and CBC modes only, default=Pkcs5) opts : Type: [Cipher.Opts](#T_Cipher_Opts) Advanced options. Use Cipher.Opts.PrefixIV to expect the IV to be prepended to the input. #### Return Value 0 if successful or non-zero [error code](#errorcodes) #### Remarks fileOut and fileIn must **not** be the same #### See Also VB6/C equivalent: [`CIPHER_FileDecrypt`](#CIPHER_FileDecrypt) [[Contents](#topofpage)] [[Index](#index)] --- ### Cipher.FileDecrypt Method (String, String, String, String, CipherAlgorithm, Mode, Padding, Cipher.Opts) Decrypt a file passing key and IV as hex strings. #### Syntax [`C#`] ``` public static int FileDecrypt( string fileOut, string fileIn, string keyHex, string ivHex, CipherAlgorithm cipherAlg, Mode mode, Padding pad, Cipher.Opts opts ) ``` [`VB.NET`] ``` Public Shared Function FileDecrypt ( _ fileOut As String, _ fileIn As String, _ keyHex As String, _ ivHex As String, _ cipherAlg As CipherAlgorithm, _ mode As Mode, _ pad As Padding, _ opts As Cipher.Opts _ ) As Integer ``` #### Parameters fileOut : Name of output file to be created or overwritten fileIn : Name of input file, in binary format. keyHex : Hex-encoded key of exact length ivHex : Hex-encoded IV, or "" for ECB mode or if IV is prefixed. cipherAlg : Type: [CipherAlgorithm](#T_CipherAlgorithm) Cipher Algorithm mode : Type: [Mode](#T_Mode) Cipher Mode pad : Type: [Padding](#T_Padding) Padding method to use (optional, ECB and CBC modes only, default=Pkcs5) opts : Type: [Cipher.Opts](#T_Cipher_Opts) Advanced options. Use Cipher.Opts.PrefixIV to expect the IV to be prepended to the input. #### Return Value 0 if successful or non-zero [error code](#errorcodes) #### Remarks fileOut and fileIn must **not** be the same. The output file is in binary format. #### See Also VB6/C equivalent: [`CIPHER_FileDecrypt`](#CIPHER_FileDecrypt) [[Contents](#topofpage)] [[Index](#index)] --- ### Cipher.FileEncrypt Method (String, String, Byte[], Byte[], CipherAlgorithm, Mode, Padding, Cipher.Opts) Encrypt a file. #### Syntax [`C#`] ``` public static int FileEncrypt( string fileOut, string fileIn, byte[] key, byte[] iv, CipherAlgorithm cipherAlg, Mode mode, Padding pad, Cipher.Opts opts ) ``` [`VB.NET`] ``` Public Shared Function FileEncrypt ( _ fileOut As String, _ fileIn As String, _ key As Byte(), _ iv As Byte(), _ cipherAlg As CipherAlgorithm, _ mode As Mode, _ pad As Padding, _ opts As Cipher.Opts _ ) As Integer ``` #### Parameters fileOut : Name of output file to be created or overwritten fileIn : Name of input file key : Key of of exact length for block cipher algorithm iv : Initialization Vector (IV) of exactly the block size or null for ECB mode cipherAlg : Type: [CipherAlgorithm](#T_CipherAlgorithm) Cipher Algorithm mode : Type: [Mode](#T_Mode) Cipher Mode pad : Type: [Padding](#T_Padding) Padding method to use (optional, ECB and CBC modes only, default=Pkcs5) opts : Type: [Cipher.Opts](#T_Cipher_Opts) Advanced options. Use Cipher.Opts.PrefixIV to prepend the IV to the output. #### Return Value 0 if successful or non-zero [error code](#errorcodes) #### Remarks fileOut and fileIn must **not** be the same #### See Also VB6/C equivalent: [`CIPHER_FileEncrypt`](#CIPHER_FileEncrypt) [[Contents](#topofpage)] [[Index](#index)] --- ### Cipher.FileEncrypt Method (String, String, String, String, CipherAlgorithm, Mode, Padding, Cipher.Opts) Encrypt a file passing key and IV as hex strings. #### Syntax [`C#`] ``` public static int FileEncrypt( string fileOut, string fileIn, string keyHex, string ivHex, CipherAlgorithm cipherAlg, Mode mode, Padding pad, Cipher.Opts opts ) ``` [`VB.NET`] ``` Public Shared Function FileEncrypt ( _ fileOut As String, _ fileIn As String, _ keyHex As String, _ ivHex As String, _ cipherAlg As CipherAlgorithm, _ mode As Mode, _ pad As Padding, _ opts As Cipher.Opts _ ) As Integer ``` #### Parameters fileOut : Name of output file to be created or overwritten fileIn : Name of input file, in binary format. keyHex : Hex-encoded key of exact length ivHex : Hex-encoded IV or "" for ECB mode cipherAlg : Type: [CipherAlgorithm](#T_CipherAlgorithm) Cipher Algorithm mode : Type: [Mode](#T_Mode) Cipher Mode pad : Type: [Padding](#T_Padding) Padding method to use (optional, ECB and CBC modes only, default=Pkcs5) opts : Type: [Cipher.Opts](#T_Cipher_Opts) Advanced options. Use Cipher.Opts.PrefixIV to prepend the IV to the output. #### Return Value 0 if successful or non-zero [error code](#errorcodes) #### Remarks fileOut and fileIn must **not** be the same. The output file is in binary format. #### See Also VB6/C equivalent: [`CIPHER_FileEncrypt`](#CIPHER_FileEncrypt) [[Contents](#topofpage)] [[Index](#index)] --- ### Cipher.KeyBytes Method Return the key size in bytes for a given cipher algorithm. #### Syntax [`C#`] ``` public static int KeyBytes( CipherAlgorithm alg ) ``` [`VB.NET`] ``` Public Shared Function KeyBytes ( _ alg As CipherAlgorithm _ ) As Integer ``` #### Parameters alg : Type: [CipherAlgorithm](#T_CipherAlgorithm) Cipher algorithm #### Return Value Key size in bytes [[Contents](#topofpage)] [[Index](#index)] --- ### Cipher.KeyUnwrap Method Unwrap (decrypt) key material with a key-encryption key. #### Syntax [`C#`] ``` public static byte[] KeyUnwrap( byte[] data, byte[] kek, CipherAlgorithm cipherAlg ) ``` [`VB.NET`] ``` Public Shared Function KeyUnwrap ( _ data As Byte(), _ kek As Byte(), _ cipherAlg As CipherAlgorithm _ ) As Byte() ``` #### Parameters data : Wrapped key kek : Key encryption key cipherAlg : Type: [CipherAlgorithm](#T_CipherAlgorithm) Block cipher to use for wrapping #### Return Value Unwrapped key material (or empty array on error) #### See Also VB6/C equivalent: [`CIPHER_KeyUnwrap`](#CIPHER_KeyUnwrap) [[Contents](#topofpage)] [[Index](#index)] --- ### Cipher.KeyWrap Method Wrap (encrypt) key material with a key-encryption key. #### Syntax [`C#`] ``` public static byte[] KeyWrap( byte[] data, byte[] kek, CipherAlgorithm cipherAlg ) ``` [`VB.NET`] ``` Public Shared Function KeyWrap ( _ data As Byte(), _ kek As Byte(), _ cipherAlg As CipherAlgorithm _ ) As Byte() ``` #### Parameters data : Key material to be wrapped kek : Key encryption key cipherAlg : Type: [CipherAlgorithm](#T_CipherAlgorithm) Block cipher to use for wrapping #### Return Value Wrapped key (or empty array on error) #### See Also VB6/C equivalent: [`CIPHER_KeyWrap`](#CIPHER_KeyWrap) [[Contents](#topofpage)] [[Index](#index)] --- ### Cipher.Pad Method (Byte[], CipherAlgorithm, Padding) Pad byte array to correct length for ECB and CBC encryption. #### Syntax [`C#`] ``` public static byte[] Pad( byte[] input, CipherAlgorithm cipherAlg, Padding pad ) ``` [`VB.NET`] ``` Public Shared Function Pad ( _ input As Byte(), _ cipherAlg As CipherAlgorithm, _ pad As Padding _ ) As Byte() ``` #### Parameters input : Data to be padded cipherAlg : Type: [CipherAlgorithm](#T_CipherAlgorithm) Block cipher being used pad : Type: [Padding](#T_Padding) Padding method to use (default is PKCS#5/#7) #### Return Value Padded data in byte array #### See Also VB6/C equivalent: [`PAD_BytesBlock`](#PAD_BytesBlock) [[Contents](#topofpage)] [[Index](#index)] --- ### Cipher.Pad Method (String, CipherAlgorithm, Padding) Pad hex-encoded string to correct length for ECB and CBC encryption. #### Syntax [`C#`] ``` public static string Pad( string inputHex, CipherAlgorithm cipherAlg, Padding pad ) ``` [`VB.NET`] ``` Public Shared Function Pad ( _ inputHex As String, _ cipherAlg As CipherAlgorithm, _ pad As Padding _ ) As String ``` #### Parameters inputHex : Hex-encoded data to be padded cipherAlg : Type: [CipherAlgorithm](#T_CipherAlgorithm) Block cipher being used pad : Type: [Padding](#T_Padding) Padding method to use (default is PKCS#5/#7) #### Return Value Padded data in hex-encoded string #### See Also VB6/C equivalent: [`PAD_HexBlock`](#PAD_HexBlock) [[Contents](#topofpage)] [[Index](#index)] --- ### Cipher.Unpad Method (Byte[], CipherAlgorithm, Padding) Remove padding from an encryption block. #### Syntax [`C#`] ``` public static byte[] Unpad( byte[] input, CipherAlgorithm cipherAlg, Padding pad ) ``` [`VB.NET`] ``` Public Shared Function Unpad ( _ input As Byte(), _ cipherAlg As CipherAlgorithm, _ pad As Padding _ ) As Byte() ``` #### Parameters input : Padded data cipherAlg : Type: [CipherAlgorithm](#T_CipherAlgorithm) Block cipher being used pad : Type: [Padding](#T_Padding) Padding method to use (default is PKCS#5/#7) #### Return Value Unpadded data in byte array. #### Remarks Unless pad is NoPad, the unpadded output is *always* shorter than the padded input. An error is indicated by returning the *original* data. If the output length equals the input length, then error. #### See Also VB6/C equivalent: [`PAD_UnpadBytes`](#PAD_UnpadBytes) [[Contents](#topofpage)] [[Index](#index)] --- ### Cipher.Unpad Method (String, CipherAlgorithm, Padding) Remove padding from a hex-encoded encryption block. #### Syntax [`C#`] ``` public static string Unpad( string inputHex, CipherAlgorithm cipherAlg, Padding pad ) ``` [`VB.NET`] ``` Public Shared Function Unpad ( _ inputHex As String, _ cipherAlg As CipherAlgorithm, _ pad As Padding _ ) As String ``` #### Parameters inputHex : Hex-encoded padded data cipherAlg : Type: [CipherAlgorithm](#T_CipherAlgorithm) Block cipher being used pad : Type: [Padding](#T_Padding) Padding method to use (default is PKCS#5/#7) #### Return Value Unpadded data in hex-encoded string. #### Remarks Unless pad is NoPad, the unpadded output is *always* shorter than the padded input. An error is indicated by returning the *original* data. If the output length equals the input length, then error. #### See Also VB6/C equivalent: [`PAD_UnpadHex`](#PAD_UnpadHex) [[Contents](#topofpage)] [[Index](#index)] --- ### Cms.GetSigDataDigest Method Extract the message digest from a signed-data CMS object file and verify the signature. #### Syntax [`C#`] ``` public static string GetSigDataDigest( string inputFile, string certFile ) ``` [`VB.NET`] ``` Public Shared Function GetSigDataDigest ( _ inputFile As String, _ certFile As String _ ) As String ``` #### Parameters inputFile : name of file containing CMS signed-data object certFile : an (optional) X.509 certificate file to be used to identify the signer #### Return Value Hash value in hex format or an empty string if error #### Remarks If no certificate is given, it will use the first valid SignerInfo and certificate pair it finds in the SignedData. RSASSA-PKCS1V1_5 only. #### See Also VB6/C equivalent: [`CMS_GetSigDataDigest`](#CMS_GetSigDataDigest) [[Contents](#topofpage)] [[Index](#index)] --- ### Cms.GetSigHashAlgorithm Method Find ID of message digest hash algorithm used to make signature. #### Syntax [`C#`] ``` public static int GetSigHashAlgorithm( string inputFile, string certFile ) ``` [`VB.NET`] ``` Public Shared Function GetSigHashAlgorithm ( _ inputFile As String, _ certFile As String _ ) As Integer ``` #### Parameters inputFile : name of file containing CMS signed-data object certFile : an (optional) X.509 certificate file to be used to identify the signer #### Return Value 0=SHA-1, 1=MD5, 2=MD2, 3=SHA-256, 4=SHA-384, 5=SHA-512, 6=SHA-224; or a negative [error code](#errorcodes) #### Remarks This method returns an integer ID number. Alternatively, use Cms.QuerySigData(inputFile, "digestAlgorithm") to get the name directly as a string, e.g. "sha1". See QuerySigData(String, String) [[Contents](#topofpage)] [[Index](#index)] --- ### Cms.MakeComprData Method Create a new CMS compressed-data file (.p7z) from an existing input file. #### Syntax [`C#`] ``` public static int MakeComprData( string outputFile, string inputFile ) ``` [`VB.NET`] ``` Public Shared Function MakeComprData ( _ outputFile As String, _ inputFile As String _ ) As Integer ``` #### Parameters outputFile : Output file to be created inputFile : Input data file #### Return Value Zero if successful; otherwise it returns a non-zero [error code](#errorcodes) #### See Also VB6/C equivalent: [`CMS_MakeComprData`](#CMS_MakeComprData) [[Contents](#topofpage)] [[Index](#index)] --- ### Cms.MakeDetachedSig Method Create a "detached signature" CMS signed-data object file from a **message digest** of the content (advanced algorithms). #### Syntax [`C#`] ``` public static int MakeDetachedSig( string outputFile, string hexDigest, string certList, string privateKey, HashAlgorithm hashAlg, Cms.SigDataOptions advOptions ) ``` [`VB.NET`] ``` Public Shared Function MakeDetachedSig ( _ outputFile As String, _ hexDigest As String, _ certList As String, _ privateKey As String, _ hashAlg As HashAlgorithm, _ advOptions As Cms.SigDataOptions _ ) As Integer ``` #### Parameters outputFile : name of output file to be created hexDigest : string containing message digest in hex format certList : filename of the signer's certificate and (optionally) a list of other certificates to be included in the output, separated by semi-colons (;) Alternatively specify a single PKCS#7 certificate chain file (.p7c/.p7b) containing the signer's certificate. privateKey : Private key data for the sender. hashAlg : Type: [HashAlgorithm](#T_HashAlgorithm) Message digest algorithm to be used in signature [default=SHA-1] advOptions : Type: [Cms.SigDataOptions](#T_Cms_SigDataOptions) Advanced option flags. See Cms.SigDataOptions. #### Return Value Zero if successful; otherwise it returns an [error code](#errorcodes) #### Remarks RSASSA-PKCS1V1_5 only. #### See Also VB6/C equivalent: [`CMS_MakeDetachedSig`](#CMS_MakeDetachedSig) [[Contents](#topofpage)] [[Index](#index)] --- ### Cms.MakeEnvData Method (String, String, String, CipherAlgorithm, Cms.EnvDataOptions) Create a CMS enveloped-data object (default recipient parameters). #### Syntax [`C#`] ``` public static int MakeEnvData( string outputFile, string inputFile, string certList, CipherAlgorithm cipherAlg, Cms.EnvDataOptions advOptions ) ``` [`VB.NET`] ``` Public Shared Function MakeEnvData ( _ outputFile As String, _ inputFile As String, _ certList As String, _ cipherAlg As CipherAlgorithm, _ advOptions As Cms.EnvDataOptions _ ) As Integer ``` #### Parameters outputFile : Name of output file to be created. inputFile : Input data file. certList : List of recipient X.509 certificate filename(s), separated by semi-colons (;). Alternatively, specify a single PKCS#7 certificate chain file (.p7c/.p7b). cipherAlg : Type: [CipherAlgorithm](#T_CipherAlgorithm) Content encryption algorithm [default=Triple DES]. advOptions : Type: [Cms.EnvDataOptions](#T_Cms_EnvDataOptions) Advanced options. See Cms.EnvDataOptions. #### Return Value Number of successful recipients or a negative [error code](#errorcodes). #### See Also VB6/C equivalent: [`CMS_MakeEnvData`](#CMS_MakeEnvData) [[Contents](#topofpage)] [[Index](#index)] --- ### Cms.MakeEnvData Method (String, String, String, CipherAlgorithm, Cms.KeyEncrAlgorithm, HashAlgorithm, Cms.EnvDataOptions, Kdf.KdfAlg, Kdf.KeyWrapAlg, String, Int32, Cms.ContentEncrAlg) Create a CMS enveloped-data object (advanced options). #### Syntax [`C#`] ``` public static int MakeEnvData( string outputFile, string inputFile, string certList, CipherAlgorithm cipherAlg, Cms.KeyEncrAlgorithm keyEncrAlg, HashAlgorithm hashAlg, Cms.EnvDataOptions advOptions, Kdf.KdfAlg kdfAlg, Kdf.KeyWrapAlg keyWrapAlg, string keyString, int count, Cms.ContentEncrAlg contEncrAlg ) ``` [`VB.NET`] ``` Public Shared Function MakeEnvData ( _ outputFile As String, _ inputFile As String, _ certList As String, _ cipherAlg As CipherAlgorithm, _ keyEncrAlg As Cms.KeyEncrAlgorithm, _ hashAlg As HashAlgorithm, _ advOptions As Cms.EnvDataOptions, _ kdfAlg As Kdf.KdfAlg, _ keyWrapAlg As Kdf.KeyWrapAlg, _ keyString As String, _ count As Integer, _ contEncrAlg As Cms.ContentEncrAlg _ ) As Integer ``` #### Parameters outputFile : Name of output file to be created. inputFile : Input data file. certList : List of one or more recipient X.509 certificate filenames, separated by semicolons (;). A certificate's representation in base64 or as a PEM string may be used instead of a filename. Alternatively, specify a single PKCS#7 certificate chain file (.p7c/.p7b). *Special cases:* Set as "type=@pwri" to create a single recipientInfo of the PasswordRecipientInfo (pwri) type; or set as "type=@kekri,keyid=" to create a single recipientInfo of the KEKRecipientInfo (kekri) type. See Remarks. cipherAlg : Type: [CipherAlgorithm](#T_CipherAlgorithm) Content encryption algorithm [default=Triple DES]. Deprecated: use contEncrAlg. keyEncrAlg : Type: [Cms.KeyEncrAlgorithm](#T_Cms_KeyEncrAlgorithm) Key encryption algorithm for ktri type [default=RSAES-PKCS-v1_5)] hashAlg : Type: [HashAlgorithm](#T_HashAlgorithm) Hash function for RSAES-OAEP or ECDH KDF or pwri PBKDF2, if required. Must be one of the SHA-* family [default=SHA-1] advOptions : Type: [Cms.EnvDataOptions](#T_Cms_EnvDataOptions) Advanced options. See Cms.EnvDataOptions. kdfAlg : Type: [Kdf.KdfAlg](#T_Kdf_KdfAlg) Key derivation function (KDF) for ECDH key agreement scheme (where applicable) keyWrapAlg : Type: [Kdf.KeyWrapAlg](#T_Kdf_KeyWrapAlg) Key wrap algorithm for ECDH key agreement scheme or kekri type (default=match content encryption algorithm) keyString : (formerly ukmString) Use to pass optional additional user key material (ukm) for KDF where KeyAgreement (kari) type is used. Or use to pass the password for a pwri type or the key encryption key (KEK) for a kekri type. Either pass a plain ASCII string, e.g. "abc" or use the format "#x" to pass a string of arbitrary octet values, e.g. "#xdeadbeef01" to pass the 5 bytes 0xde,0xad,0xbe,0xef,0x01. Required for pwri and kekri types. count : Optional iteration count for KDF in pwri type (default=4096) or tag length for AuthEnvelopedData (in range 12-16, default=16). Otherwise ignored. contEncrAlg : Type: [Cms.ContentEncrAlg](#T_Cms_ContentEncrAlg) Alternative way to specify content encryption algorithm with more options. Takes precedence over cipherAlg. #### Return Value Number of successful recipients or a negative [error code](#errorcodes). #### Remarks The output is a file containing a CMS EnvelopedData object or AuthEnvelopedData object. *New in [v22.0]* use the preferred contEncrAlg parameter to specify the content-encryption algorithm rather than cipherAlg. If a list of certificates is passed in certList, the recipientInfo type is set automatically depending on the public key found in each certificate, one for each certificate. If the public key is RSA (rsaEncryption) then the key transport technique (ktri) will be used for that particular recipientInfo. If the public key is a supported ECC key, then the standard ECDH ephemeral-static key agreement technique (kari) will be used as per [RFC5753] and [RFC8418]. If certList is set to "type=@pwri" then a single recipientInfo will be created of PasswordRecipientInfo type (pwri). The password must be passed in the keyString parameter. The parameters keyEncrAlg, kdfAlg and keyWrapAlg are ignored in this case. If certList is set to "type=@kekri,keyid=" then a single recipientInfo will be created of KEKRecipientInfo type (kekri). The key encryption key (KEK) must be passed in the keyString parameter. The parameters keyEncrAlg, hashAlg and kdfAlg are ignored in this case. #### Example [`C#`] ``` // Create an enveloped CMS object (ktri type) to Bob using Bob's RSA key n = Cms.MakeEnvData("cms2bob_aes128.p7m", "excontent.txt", "BobRSASignByCarl.cer", CipherAlgorithm.Aes128, Cms.KeyEncrAlgorithm.Rsa_Oaep); // Create an enveloped CMS object (kekri type) using a previously distributed symmetric key-encryption key (KEK) n = Cms.MakeEnvData("cms_envdata_kekri.p7m", "excontent.txt", "type=@kekri,keyid=ourcommonkey", CipherAlgorithm.Aes256, hashAlg: HashAlgorithm.Sha256, keyWrapAlg:Kdf.KeyWrapAlg.Aes128_wrap, keyString: "#x0123456789ABCDEFF0E1D2C3B4A59687"); ``` #### See Also VB6/C equivalent: [`CMS_MakeEnvData`](#CMS_MakeEnvData) [[Contents](#topofpage)] [[Index](#index)] --- ### Cms.MakeEnvDataFromBytes Method Create a CMS enveloped-data object from data in a byte array. #### Syntax [`C#`] ``` public static int MakeEnvDataFromBytes( string outputFile, byte[] inputData, string certList, CipherAlgorithm cipherAlg, Cms.KeyEncrAlgorithm keyEncrAlg, HashAlgorithm hashAlg, Cms.EnvDataOptions advOptions, Kdf.KdfAlg kdfAlg, Kdf.KeyWrapAlg keyWrapAlg, string keyString, int count, Cms.ContentEncrAlg contEncrAlg ) ``` [`VB.NET`] ``` Public Shared Function MakeEnvDataFromBytes ( _ outputFile As String, _ inputData As Byte(), _ certList As String, _ cipherAlg As CipherAlgorithm, _ keyEncrAlg As Cms.KeyEncrAlgorithm, _ hashAlg As HashAlgorithm, _ advOptions As Cms.EnvDataOptions, _ kdfAlg As Kdf.KdfAlg, _ keyWrapAlg As Kdf.KeyWrapAlg, _ keyString As String, _ count As Integer, _ contEncrAlg As Cms.ContentEncrAlg _ ) As Integer ``` #### Parameters outputFile : Output file to be created inputData : Input data. certList : List of one or more recipient X.509 certificate filenames, separated by semicolons (;). A certificate's representation in base64 or as a PEM string may be used instead of a filename. Alternatively, specify a single PKCS#7 certificate chain file (.p7c/.p7b). *Special cases:* Set as "type=@pwri" to create a single recipientInfo of the PasswordRecipientInfo (pwri) type; or set as "type=@kekri,keyid=" to create a single recipientInfo of the KEKRecipientInfo (kekri) type. See Remarks. cipherAlg : Type: [CipherAlgorithm](#T_CipherAlgorithm) Content encryption algorithm [default=Triple DES]. Deprecated: use contEncrAlg. keyEncrAlg : Type: [Cms.KeyEncrAlgorithm](#T_Cms_KeyEncrAlgorithm) Key encryption algorithm for ktri type [default=RSAES-PKCS-v1_5)] hashAlg : Type: [HashAlgorithm](#T_HashAlgorithm) Hash function for RSAES-OAEP or ECDH KDF or pwri PBKDF2, if required. Must be one of the SHA-* family [default=SHA-1] advOptions : Type: [Cms.EnvDataOptions](#T_Cms_EnvDataOptions) Advanced options. See Cms.EnvDataOptions. kdfAlg : Type: [Kdf.KdfAlg](#T_Kdf_KdfAlg) Key derivation function (KDF) for ECDH key agreement scheme (where applicable) keyWrapAlg : Type: [Kdf.KeyWrapAlg](#T_Kdf_KeyWrapAlg) Key wrap algorithm for ECDH key agreement scheme or kekri type (default=match content encryption algorithm) keyString : (formerly ukmString) Use to pass optional additional user key material (ukm) for KDF where KeyAgreement (kari) type is used. Or use to pass the password for a pwri type or the key encryption key (KEK) for a kekri type. Either pass a plain ASCII string, e.g. "abc" or use the format "#x" to pass a string of arbitrary octet values, e.g. "#xdeadbeef01" to pass the 5 bytes 0xde,0xad,0xbe,0xef,0x01. Required for pwri and kekri types. count : Optional iteration count for KDF in pwri type (default=4096) or tag length for AuthEnvelopedData (in range 12-16, default=16). Otherwise ignored. contEncrAlg : Type: [Cms.ContentEncrAlg](#T_Cms_ContentEncrAlg) Alternative way to specify content encryption algorithm with more options. Takes precedence over cipherAlg. #### Return Value Number of successful recipients or negative [error code](#errorcodes) #### Remarks See remarks for MakeEnvData(String, String, String, CipherAlgorithm, Cms.KeyEncrAlgorithm, HashAlgorithm, Cms.EnvDataOptions, Kdf.KdfAlg, Kdf.KeyWrapAlg, String, Int32, Cms.ContentEncrAlg) #### See Also VB6/C equivalent: [`CMS_MakeEnvDataFromBytes`](#CMS_MakeEnvDataFromBytes) [[Contents](#topofpage)] [[Index](#index)] --- ### Cms.MakeEnvDataFromString Method (String, String, String, CipherAlgorithm, Cms.EnvDataOptions) Create a CMS enveloped-data object from an ASCII string (default recipient parameters). #### Syntax [`C#`] ``` public static int MakeEnvDataFromString( string outputFile, string inputData, string certList, CipherAlgorithm cipherAlg, Cms.EnvDataOptions advOptions ) ``` [`VB.NET`] ``` Public Shared Function MakeEnvDataFromString ( _ outputFile As String, _ inputData As String, _ certList As String, _ cipherAlg As CipherAlgorithm, _ advOptions As Cms.EnvDataOptions _ ) As Integer ``` #### Parameters outputFile : Output file to be created inputData : Input data string, expected plain ASCII text. certList : List of recipient X.509 certificate filename(s), separated by semi-colons (;). Alternatively, specify a single PKCS#7 certificate chain file (.p7c/.p7b). cipherAlg : Type: [CipherAlgorithm](#T_CipherAlgorithm) Content encryption algorithm [default=Triple DES] advOptions : Type: [Cms.EnvDataOptions](#T_Cms_EnvDataOptions) Advanced options. See Cms.EnvDataOptions. #### Return Value Number of successful recipients or negative [error code](#errorcodes) #### See Also VB6/C equivalent: [`CMS_MakeEnvDataFromString`](#CMS_MakeEnvDataFromString) [[Contents](#topofpage)] [[Index](#index)] --- ### Cms.MakeEnvDataFromString Method (String, String, String, CipherAlgorithm, Cms.KeyEncrAlgorithm, HashAlgorithm, Cms.EnvDataOptions, Kdf.KdfAlg, Kdf.KeyWrapAlg, String, Int32, Cms.ContentEncrAlg) Create a CMS enveloped-data object from an ASCII string (advanced options). #### Syntax [`C#`] ``` public static int MakeEnvDataFromString( string outputFile, string inputData, string certList, CipherAlgorithm cipherAlg, Cms.KeyEncrAlgorithm keyEncrAlg, HashAlgorithm hashAlg, Cms.EnvDataOptions advOptions, Kdf.KdfAlg kdfAlg, Kdf.KeyWrapAlg keyWrapAlg, string keyString, int count, Cms.ContentEncrAlg contEncrAlg ) ``` [`VB.NET`] ``` Public Shared Function MakeEnvDataFromString ( _ outputFile As String, _ inputData As String, _ certList As String, _ cipherAlg As CipherAlgorithm, _ keyEncrAlg As Cms.KeyEncrAlgorithm, _ hashAlg As HashAlgorithm, _ advOptions As Cms.EnvDataOptions, _ kdfAlg As Kdf.KdfAlg, _ keyWrapAlg As Kdf.KeyWrapAlg, _ keyString As String, _ count As Integer, _ contEncrAlg As Cms.ContentEncrAlg _ ) As Integer ``` #### Parameters outputFile : Output file to be created inputData : Input data string, expected plain ASCII text. certList : List of recipient X.509 certificate filename(s), separated by semi-colons (;). Alternatively, specify a single PKCS#7 certificate chain file (.p7c/.p7b). *Special cases:* Set as "type=@pwri" to create a single recipientInfo of the PasswordRecipientInfo type (pwri); or set as "type=@kekri,keyid=" to create a single recipientInfo of the KEKRecipientInfo type (kekri). See Remarks. cipherAlg : Type: [CipherAlgorithm](#T_CipherAlgorithm) Content encryption algorithm [default=Triple DES]. Deprecated: use contEncrAlg. keyEncrAlg : Type: [Cms.KeyEncrAlgorithm](#T_Cms_KeyEncrAlgorithm) Key encryption algorithm [default=rsaEncryption)] hashAlg : Type: [HashAlgorithm](#T_HashAlgorithm) Hash function for RSAES-OAEP or ECDH KDF or PBKDF2 for pwri, if required. Must be one of the SHA-* family [default=SHA-1] advOptions : Type: [Cms.EnvDataOptions](#T_Cms_EnvDataOptions) Advanced options. See Cms.EnvDataOptions. kdfAlg : Type: [Kdf.KdfAlg](#T_Kdf_KdfAlg) Key derivation function (KDF) for ECDH key agreement scheme (where applicable) keyWrapAlg : Type: [Kdf.KeyWrapAlg](#T_Kdf_KeyWrapAlg) Key wrap algorithm for ECDH key agreement scheme (default=match content encryption algorithm) keyString : (formerly ukmString) Use to pass optional additional user key material (ukm) for KDF where KeyAgreement (kari) type is used. Or use to pass the password for a pwri type or the key encryption key (KEK) for a kekri type. Either pass a plain ASCII string, e.g. "abc" or use the format "#x" to pass a string of arbitrary octet values, e.g. "#xdeadbeef01" to pass the 5 bytes 0xde,0xad,0xbe,0xef,0x01. Optional for kari types but required for pwri and kekri types. count : Optional iteration count for KDF in pwri type (default=4096) or tag length for AuthEnvelopedData (in range 12-16, default=16). Otherwise ignored. contEncrAlg : Type: [Cms.ContentEncrAlg](#T_Cms_ContentEncrAlg) Alternative way to specify content encryption algorithm with more options. Takes precedence over cipherAlg. #### Return Value Number of successful recipients or negative [error code](#errorcodes) #### Remarks See remarks for MakeEnvData(String, String, String, CipherAlgorithm, Cms.KeyEncrAlgorithm, HashAlgorithm, Cms.EnvDataOptions, Kdf.KdfAlg, Kdf.KeyWrapAlg, String, Int32, Cms.ContentEncrAlg) #### See Also VB6/C equivalent: [`CMS_MakeEnvDataFromString`](#CMS_MakeEnvDataFromString) [[Contents](#topofpage)] [[Index](#index)] --- ### Cms.MakeSigData Method (String, String, String, String, Cms.SigAlg, Cms.SigDataOptions) Create a CMS object of type SignedData from an input data file (advanced options including RSA-PSS). #### Syntax [`C#`] ``` public static int MakeSigData( string outputFile, string inputFile, string certList, string privateKey, Cms.SigAlg sigAlg, Cms.SigDataOptions advOptions ) ``` [`VB.NET`] ``` Public Shared Function MakeSigData ( _ outputFile As String, _ inputFile As String, _ certList As String, _ privateKey As String, _ sigAlg As Cms.SigAlg, _ advOptions As Cms.SigDataOptions _ ) As Integer ``` #### Parameters outputFile : name of output file to be created inputFile : name of file containing message data to be signed certList : filename of the signer's certificate and (optionally) a list of other certificates to be included in the output, separated by semi-colons (;) Alternatively specify a single PKCS#7 certificate chain file (.p7c/.p7b) containing the signer's certificate. privateKey : private key data for the sender sigAlg : Type: [Cms.SigAlg](#T_Cms_SigAlg) Signature algorithm. advOptions : Type: [Cms.SigDataOptions](#T_Cms_SigDataOptions) Advanced option flags. See Cms.SigDataOptions. #### Return Value Zero if successful; otherwise it returns an [error code](#errorcodes) #### Example [`C#`] ``` StringBuilder sbPrivateKey = Rsa.ReadPrivateKey("AlicePrivRSASign.p8e", "password"); string fnameOutput = "BasicSignByAlice.bin"; string fnameInput = "excontent.txt"; string fnameCert = "AliceRSASignByCarl.cer"; int n = Cms.MakeSigData(fnameOutput, fnameInput, fnameCert, sbPrivateKey.ToString(), Cms.SigAlg.Default, 0); ``` #### See Also VB6/C equivalent: [`CMS_MakeSigData`](#CMS_MakeSigData) [[Contents](#topofpage)] [[Index](#index)] --- ### Cms.MakeSigData Method (String, String, String, String, HashAlgorithm, Cms.SigDataOptions) Create a CMS object of type SignedData from an input data file using RSASSA-PKCS1V1_5 with options. #### Syntax [`C#`] ``` public static int MakeSigData( string outputFile, string inputFile, string certList, string privateKey, HashAlgorithm hashAlg, Cms.SigDataOptions advOptions ) ``` [`VB.NET`] ``` Public Shared Function MakeSigData ( _ outputFile As String, _ inputFile As String, _ certList As String, _ privateKey As String, _ hashAlg As HashAlgorithm, _ advOptions As Cms.SigDataOptions _ ) As Integer ``` #### Parameters outputFile : name of output file to be created inputFile : name of file containing message data to be signed certList : filename of the signer's certificate and (optionally) a list of other certificates to be included in the output, separated by semi-colons (;) Alternatively specify a single PKCS#7 certificate chain file (.p7c/.p7b) containing the signer's certificate. privateKey : private key data for the sender hashAlg : Type: [HashAlgorithm](#T_HashAlgorithm) Message digest algorithm to be used in signature [default=SHA-1]. advOptions : Type: [Cms.SigDataOptions](#T_Cms_SigDataOptions) Advanced option flags. See Cms.SigDataOptions. #### Return Value Zero if successful; otherwise it returns an [error code](#errorcodes) #### Remarks RSASSA-PKCS1V1_5 only. #### See Also VB6/C equivalent: [`CMS_MakeSigData`](#CMS_MakeSigData) [[Contents](#topofpage)] [[Index](#index)] --- ### Cms.MakeSigDataFromBytes Method Create a CMS object of type SignedData from an array of bytes. #### Syntax [`C#`] ``` public static int MakeSigDataFromBytes( string outputFile, byte[] inputData, string certList, string privateKey, Cms.SigAlg sigAlg, Cms.SigDataOptions advOptions ) ``` [`VB.NET`] ``` Public Shared Function MakeSigDataFromBytes ( _ outputFile As String, _ inputData As Byte(), _ certList As String, _ privateKey As String, _ sigAlg As Cms.SigAlg, _ advOptions As Cms.SigDataOptions _ ) As Integer ``` #### Parameters outputFile : name of output file to be created. inputData : message data to be signed in a byte array. certList : filename of the signer's certificate and (optionally) a list of other certificates to be included in the output, separated by semi-colons (;) Alternatively specify a single PKCS#7 certificate chain file (.p7c/.p7b) containing the signer's certificate. privateKey : Private key data for the sender. sigAlg : Type: [Cms.SigAlg](#T_Cms_SigAlg) Signature algorithm. advOptions : Type: [Cms.SigDataOptions](#T_Cms_SigDataOptions) Advanced option flags. See Cms.SigDataOptions. #### Return Value Zero if successful; otherwise it returns an [error code](#errorcodes) #### See Also VB6/C equivalent: [`CMS_MakeSigDataFromBytes`](#CMS_MakeSigDataFromBytes) [[Contents](#topofpage)] [[Index](#index)] --- ### Cms.MakeSigDataFromPseudo Method Create a SignedData object from a "pseudo" object. #### Syntax [`C#`] ``` public static int MakeSigDataFromPseudo( string outputFile, string inputPseudoFile, byte[] sigValue, Cms.Format format ) ``` [`VB.NET`] ``` Public Shared Function MakeSigDataFromPseudo ( _ outputFile As String, _ inputPseudoFile As String, _ sigValue As Byte(), _ format As Cms.Format _ ) As Integer ``` #### Parameters outputFile : Name of output file to be created. inputPseudoFile : Input "pseudo" file with dummy placeholder signature. sigValue : Signature value computed by external service. format : Type: [Cms.Format](#T_Cms_Format) Output format (default = binary) #### Return Value Zero if successful; otherwise it returns an [error code](#errorcodes) #### Remarks RSASSA-PKCS1V1_5 only. #### See Also VB6/C equivalent: [`CMS_MakeSigDataFromSigValue`](#CMS_MakeSigDataFromSigValue) [[Contents](#topofpage)] [[Index](#index)] --- ### Cms.MakeSigDataFromSigValue Method Create a CMS object of type SignedData using a pre-computed signature (advanced algorithms). #### Syntax [`C#`] ``` public static int MakeSigDataFromSigValue( string outputFile, byte[] sigValue, byte[] contentData, string certList, HashAlgorithm hashAlg, Cms.SigDataOptions advOptions ) ``` [`VB.NET`] ``` Public Shared Function MakeSigDataFromSigValue ( _ outputFile As String, _ sigValue As Byte(), _ contentData As Byte(), _ certList As String, _ hashAlg As HashAlgorithm, _ advOptions As Cms.SigDataOptions _ ) As Integer ``` #### Parameters outputFile : name of output file to be created sigValue : signature value contentData : string containing content data that has been signed certList : filename of the signer's certificate and (optionally) a list of other certificates to be included in the output, separated by semi-colons (;) Alternatively specify a single PKCS#7 certificate chain file (.p7c/.p7b) containing the signer's certificate. hashAlg : Type: [HashAlgorithm](#T_HashAlgorithm) Message digest algorithm to be used in signature [default=SHA-1] advOptions : Type: [Cms.SigDataOptions](#T_Cms_SigDataOptions) Advanced option flags. See Cms.SigDataOptions. #### Return Value Zero if successful; otherwise it returns an [error code](#errorcodes) #### Remarks RSASSA-PKCS1V1_5 only. #### See Also VB6/C equivalent: [`CMS_MakeSigDataFromSigValue`](#CMS_MakeSigDataFromSigValue) [[Contents](#topofpage)] [[Index](#index)] --- ### Cms.MakeSigDataFromString Method (String, String, String, String, Cms.SigAlg, Cms.SigDataOptions) Create a CMS object of type SignedData from an input string (advanced options including RSA-PSS). #### Syntax [`C#`] ``` public static int MakeSigDataFromString( string outputFile, string inputData, string certList, string privateKey, Cms.SigAlg sigAlg, Cms.SigDataOptions advOptions ) ``` [`VB.NET`] ``` Public Shared Function MakeSigDataFromString ( _ outputFile As String, _ inputData As String, _ certList As String, _ privateKey As String, _ sigAlg As Cms.SigAlg, _ advOptions As Cms.SigDataOptions _ ) As Integer ``` #### Parameters outputFile : name of output file to be created inputData : string containing message data to be signed certList : filename of the signer's certificate and (optionally) a list of other certificates to be included in the output, separated by semi-colons (;) Alternatively specify a single PKCS#7 certificate chain file (.p7c/.p7b) containing the signer's certificate. privateKey : private key data for the sender sigAlg : Type: [Cms.SigAlg](#T_Cms_SigAlg) Signature algorithm. advOptions : Type: [Cms.SigDataOptions](#T_Cms_SigDataOptions) Advanced option flags. See Cms.SigDataOptions. #### Return Value Zero if successful; otherwise it returns an [error code](#errorcodes) #### See Also VB6/C equivalent: [`CMS_MakeSigDataFromString`](#CMS_MakeSigDataFromString) [[Contents](#topofpage)] [[Index](#index)] --- ### Cms.MakeSigDataFromString Method (String, String, String, String, HashAlgorithm, Cms.SigDataOptions) Create a CMS object of type SignedData from an input string using RSASSA-PKCS1V1_5 with options. #### Syntax [`C#`] ``` public static int MakeSigDataFromString( string outputFile, string inputData, string certList, string privateKey, HashAlgorithm hashAlg, Cms.SigDataOptions advOptions ) ``` [`VB.NET`] ``` Public Shared Function MakeSigDataFromString ( _ outputFile As String, _ inputData As String, _ certList As String, _ privateKey As String, _ hashAlg As HashAlgorithm, _ advOptions As Cms.SigDataOptions _ ) As Integer ``` #### Parameters outputFile : name of output file to be created inputData : string containing message data to be signed certList : filename of the signer's certificate and (optionally) a list of other certificates to be included in the output, separated by semi-colons (;) Alternatively specify a single PKCS#7 certificate chain file (.p7c/.p7b) containing the signer's certificate. privateKey : private key data for the sender hashAlg : Type: [HashAlgorithm](#T_HashAlgorithm) Message digest algorithm to be used in signature [default=SHA-1] advOptions : Type: [Cms.SigDataOptions](#T_Cms_SigDataOptions) Advanced option flags. See Cms.SigDataOptions. #### Return Value Zero if successful; otherwise it returns an [error code](#errorcodes) #### Remarks RSASSA-PKCS1V1_5 only. #### See Also VB6/C equivalent: [`CMS_MakeSigDataFromString`](#CMS_MakeSigDataFromString) [[Contents](#topofpage)] [[Index](#index)] --- ### Cms.QueryEnvData Method Query a CMS enveloped-data object file for selected information. #### Syntax [`C#`] ``` public static string QueryEnvData( string inputFile, string query ) ``` [`VB.NET`] ``` Public Shared Function QueryEnvData ( _ inputFile As String, _ query As String _ ) As String ``` #### Parameters inputFile : file containing CMS enveloped-data object query : Query string (case insensitive) #### Return Value String containing the result or an empty string if not found or error. #### Remarks Valid queries are: | "version" | envelopedData CMSVersion (edVer) value, e.g. "0". | | --- | --- | | "recipientInfoVersion" | recipientInfo version (riVer) value. | | "recipientInfoType" | Type of recipientInfo, e.g. ktri, kari, ... | | "CountOfRecipientInfos" | Number of RecipientInfos included in the data. | | "recipientIssuerName" | Distinguished Name of recipient's certificate issuer. | | "recipientSerialNumber" | serialNumber of recipient's certificate in hex format | | "keyEncryptionAlgorithm" | keyEncryptionAlgorithm, e.g. "rsaEncryption". | | "keyEncryptionFlags" | Bit flags used for the key encryption algorithm (ktri only). | | "SizeOfEncryptedKey" | Size (in bytes) of the EncryptedKey. | | "encryptedKey" | EncryptedKey value encoded in hex. | | "oaepParams" | Parameters used for RSA-OAEP (if applicable). | | "keyWrapAlgorithm" | Key wrap algorithm, e.g. "aes128-wrap" (kari and kekri only). | | "originatorKeyAlgorithm" | OriginatorPublicKey algorithm, e.g. "ecPublicKey" (kari only). | | "originatorPublicKey" | OriginatorPublicKey publicKey value encoded in hex (kari only). | | "keyid" | keyIdentifier for KEKRecipientInfo (kekri) type. | | "contentEncryptionAlgorithm" | contentEncryptionAlgorithm, e.g. "des-EDE3-CBC". | | "SizeOfEncryptedContent" | Size (in bytes) of the EncryptedContent. | | "encryptedContent" | EncryptedContent encoded in hex. | | "iv" | Initialization vector encoded in hex. | By default, the function queries the first recipientInfo in the file. To query the Nth recipientInfo append "/N" to the query string, e.g. "recipientInfoVersion/2" to find the version number of the second recipientInfo in the file. #### See Also VB6/C equivalent: [`CMS_QueryEnvData`](#CMS_QueryEnvData) [[Contents](#topofpage)] [[Index](#index)] --- ### Cms.QuerySigData Method Query a CMS signed-data object for selected information. #### Syntax [`C#`] ``` public static string QuerySigData( string inputFile, string query ) ``` [`VB.NET`] ``` Public Shared Function QuerySigData ( _ inputFile As String, _ query As String _ ) As String ``` #### Parameters inputFile : file containing CMS signed-data object query : Query string (case insensitive) #### Return Value String containing the result or an empty string if not found or error. #### Remarks Valid queries are: | "version" | signedData version (sdVer) value, e.g. "1". | | --- | --- | | "eContentType" | ContentType of the EncapsulatedContentInfo, e.g. "data". | | "HASeContent" | "1" if eContent is present; "0" if not. | | "CountOfCertificates" | Number of certificates included in the data. | | "CountOfSignerInfos" | Number of SignerInfos included in the data. | | "signerInfoVersion" | signerInfo version (siVer) value. | | "digestAlgorithm" | digestAlgorithm, e.g. "sha1". | | "signatureAlgorithm" | signatureAlgorithm, e.g. "rsaEncryption". | | "signatureValue" | Signature value encoded in hex. | | "HASsignedAttributes" | "1" if signedAttributes (authenticatedAttributes) are present; "0" if not. | | "DigestOfSignedAttrs" | Computed digest over signed attributes, if present, using digestAlgorithm. | | "DigestOfeContent" | Computed digest over eContent, if present, using digestAlgorithm. | | "signingTime" | signingTime attribute in format "2005-12-31 23:30:59" | | "messageDigest" | messageDigest attribute in hexadecimal format, if present | | "pssParams" | Parameters used for RSA-PSS (if applicable). | | "HASsigningCertificate" | "1" if an ESS signingCertificate is present; "0" if not. | | "signingCertHash" | certHash value of ESS signing certificate, if present, encoded in hex. | | "HASalgorithmProtection" | "1" if a cmsAlgorithmProtection attribute is present; "0" if not. | By default, the function queries the first signerInfo in the file. To query the Nth signerInfo append "/N" to the query string, e.g. "signerInfoVersion/2" to find the version number of the second signerInfo in the file. #### See Also VB6/C equivalent: [`CMS_QuerySigData`](#CMS_QuerySigData) [[Contents](#topofpage)] [[Index](#index)] --- ### Cms.ReadComprData Method Read and extract the decompressed contents of a CMS compressed-data file. #### Syntax [`C#`] ``` public static int ReadComprData( string outputFile, string inputFile, Cms.ComprDataOptions opts ) ``` [`VB.NET`] ``` Public Shared Function ReadComprData ( _ outputFile As String, _ inputFile As String, _ opts As Cms.ComprDataOptions _ ) As Integer ``` #### Parameters outputFile : Output file to be created inputFile : Input data file opts : Type: [Cms.ComprDataOptions](#T_Cms_ComprDataOptions) Options [default=inflate contents] #### Return Value If successful the return value is the number of bytes in the output file; otherwise it returns a non-zero [error code](#errorcodes) #### See Also VB6/C equivalent: [`CMS_ReadComprData`](#CMS_ReadComprData) [[Contents](#topofpage)] [[Index](#index)] --- ### Cms.ReadEnvDataToBytes Method Read and decrypt a CMS enveloped-data object to a byte array. #### Syntax [`C#`] ``` public static byte[] ReadEnvDataToBytes( string inputFile, string x509File, string privateKey ) ``` [`VB.NET`] ``` Public Shared Function ReadEnvDataToBytes ( _ inputFile As String, _ x509File As String, _ privateKey As String _ ) As Byte() ``` #### Parameters inputFile : Name of file containing CMS enveloped-data object (binary or base64-encoded) or the data as a base64 or PEM string. x509File : (optional) filename of the recipient's X.509 certificate. privateKey : Internal representation of private key. #### Return Value Decrypted content in a byte array, or empty array on error. #### Example [`C#`] ``` // Read in content to a byte array byte[] b = Cms.ReadEnvDataToBytes(inputFile, "", privateKey); // Convert to a .NET string (assuming UTF-8 encoded) string s = System.Text.Encoding.UTF8.GetString(b); ``` #### See Also VB6/C equivalent: [`CMS_ReadEnvDataToBytes`](#CMS_ReadEnvDataToBytes) [[Contents](#topofpage)] [[Index](#index)] --- ### Cms.ReadEnvDataToFile Method Read and decrypt a CMS enveloped-data object to a file. #### Syntax [`C#`] ``` public static int ReadEnvDataToFile( string outputFile, string inputFile, string x509File, string privateKey, Cms.ReadOptions opts ) ``` [`VB.NET`] ``` Public Shared Function ReadEnvDataToFile ( _ outputFile As String, _ inputFile As String, _ x509File As String, _ privateKey As String, _ opts As Cms.ReadOptions _ ) As Integer ``` #### Parameters outputFile : Name of output file to be created. inputFile : Name of file containing CMS enveloped-data object (binary or base64-encoded) or the data as a base64 or PEM string. x509File : (optional) filename of the recipient's X.509 certificate. privateKey : Internal representation of private key. opts : Type: [Cms.ReadOptions](#T_Cms_ReadOptions) Use Cms.ReadOptions for faster handling of large files (binary only). #### Return Value Zero if successful; otherwise it returns an [error code](#errorcodes). #### See Also VB6/C equivalent: [`CMS_ReadEnvData`](#CMS_ReadEnvData) [[Contents](#topofpage)] [[Index](#index)] --- ### Cms.ReadEnvDataToString Method Read and decrypt a CMS enveloped-data object to a string. #### Syntax [`C#`] ``` public static string ReadEnvDataToString( string inputFile, string x509File, string privateKey ) ``` [`VB.NET`] ``` Public Shared Function ReadEnvDataToString ( _ inputFile As String, _ x509File As String, _ privateKey As String _ ) As String ``` #### Parameters inputFile : Name of file containing CMS enveloped-data object (binary or base64-encoded) or the data as a base64 or PEM string. x509File : (optional) filename of the recipient's X.509 certificate privateKey : Internal representation of private key. #### Return Value Decrypted content in a string or empty string on error. #### Remarks Use this only when the decrypted text is known to be plain ASCII text, otherwise use ReadEnvDataToBytes. #### See Also VB6/C equivalent: [`CMS_ReadEnvDataToString`](#CMS_ReadEnvDataToString) [[Contents](#topofpage)] [[Index](#index)] --- ### Cms.ReadSigDataToBytes Method Read the content from a CMS signed-data object directly into a byte array. #### Syntax [`C#`] ``` public static byte[] ReadSigDataToBytes( string inputFile ) ``` [`VB.NET`] ``` Public Shared Function ReadSigDataToBytes ( _ inputFile As String _ ) As Byte() ``` #### Parameters inputFile : Name of file containing CMS signed-data object (binary or base64-encoded) or the data as a base64 or PEM string. #### Return Value Byte array containing the content or a zero-length array if error. #### Remarks Use this if the content contains non-ASCII characters, e.g. UTF-8 encoded. #### Example [`C#`] ``` // Read in content to a byte array byte[] b = Cms.ReadSigDataToBytes(inputFile); // Convert to a .NET string (assumed UTF-8 encoded) string s = System.Text.Encoding.UTF8.GetString(b); ``` #### See Also VB6/C equivalent: [`CMS_ReadSigDataToBytes`](#CMS_ReadSigDataToBytes) [[Contents](#topofpage)] [[Index](#index)] --- ### Cms.ReadSigDataToFile Method Read the content from a CMS signed-data object file. #### Syntax [`C#`] ``` public static int ReadSigDataToFile( string outputFile, string inputFile, Cms.ReadOptions opts ) ``` [`VB.NET`] ``` Public Shared Function ReadSigDataToFile ( _ outputFile As String, _ inputFile As String, _ opts As Cms.ReadOptions _ ) As Integer ``` #### Parameters outputFile : file to receive content inputFile : Name of file containing CMS signed-data object (binary or base64-encoded) or the data as a base64 or PEM string. opts : Type: [Cms.ReadOptions](#T_Cms_ReadOptions) Option flags: set as zero for defaults. #### Return Value If successful, the return value is a positive number indicating the number of bytes in the content; otherwise it returns a negative [error code](#errorcodes). #### See Also VB6/C equivalent: [`CMS_ReadSigData`](#CMS_ReadSigData) [[Contents](#topofpage)] [[Index](#index)] --- ### Cms.ReadSigDataToString Method Read the content from a CMS signed-data object directly into a string. #### Syntax [`C#`] ``` public static string ReadSigDataToString( string inputFile ) ``` [`VB.NET`] ``` Public Shared Function ReadSigDataToString ( _ inputFile As String _ ) As String ``` #### Parameters inputFile : Name of file containing CMS signed-data object (binary or base64-encoded) or the data as a base64 or PEM string. #### Return Value String containing the content or an empty string if error #### See Also VB6/C equivalent: [`CMS_ReadSigDataToString`](#CMS_ReadSigDataToString) [[Contents](#topofpage)] [[Index](#index)] --- ### Cms.VerifySigData Method Verify the signature and content of a signed-data CMS object file. #### Syntax [`C#`] ``` public static int VerifySigData( string inputFile, string certFile, string hexDigest, Cms.SigDataOptions advOptions ) ``` [`VB.NET`] ``` Public Shared Function VerifySigData ( _ inputFile As String, _ certFile As String, _ hexDigest As String, _ advOptions As Cms.SigDataOptions _ ) As Integer ``` #### Parameters inputFile : file containing CMS signed-data object certFile : an (optional) X.509 certificate file of the signer hexDigest : (optional) digest of eContent to be verified (use for "detached-signature" form) advOptions : Type: [Cms.SigDataOptions](#T_Cms_SigDataOptions) Use for BigFile option, otherwise ignored #### Return Value Zero if successfully verified; otherwise it returns a non-zero [error code](#errorcodes) #### See Also VB6/C equivalent: [`CMS_VerifySigData`](#CMS_VerifySigData) [[Contents](#topofpage)] [[Index](#index)] --- ### Cnv.Base64Filter Method Filter non-base64 characters from a string. #### Syntax [`C#`] ``` public static string Base64Filter( string s ) ``` [`VB.NET`] ``` Public Shared Function Base64Filter ( _ s As String _ ) As String ``` #### Parameters s : String to be filtered #### Return Value Filtered string #### Remarks Valid base64 characters are [0-9A-Za-z+/=] #### See Also VB6/C equivalent: [`CNV_B64Filter`](#CNV_B64Filter) [[Contents](#topofpage)] [[Index](#index)] --- ### Cnv.Base64FromHex Method Convert hexadecimal-encoded data into base64-encoded data. #### Syntax [`C#`] ``` public static string Base64FromHex( string s ) ``` [`VB.NET`] ``` Public Shared Function Base64FromHex ( _ s As String _ ) As String ``` #### Parameters s : Hex-encoded data #### Return Value Base64-encoded data [[Contents](#topofpage)] [[Index](#index)] --- ### Cnv.ByteEncoding Method Convert encoding of byte array between UTF-8 and Latin-1. #### Syntax [`C#`] ``` public static byte[] ByteEncoding( byte[] data, Cnv.EncodingConversion direction ) ``` [`VB.NET`] ``` Public Shared Function ByteEncoding ( _ data As Byte(), _ direction As Cnv.EncodingConversion _ ) As Byte() ``` #### Parameters data : Input data to be converted direction : Type: [Cnv.EncodingConversion](#T_Cnv_EncodingConversion) Direction of conversion #### Return Value Converted data (or empty array on error) #### Remarks Converting UTF-8 from Latin-1 assumes the input is from the 8-bit Latin-1 character set and so will *always* produce output that is valid UTF-8. However, for Latin-1 from UTF-8, the input *must* contain a valid sequence of UTF-8-encoded bytes and this must be convertible to a single-byte character set, or an error will be returned. #### See Also VB6/C equivalent: [`CNV_ByteEncoding`](#CNV_ByteEncoding) [[Contents](#topofpage)] [[Index](#index)] --- ### Cnv.CheckUTF8 Method Check that a byte array contains only valid UTF-8 encoded characters. #### Syntax [`C#`] ``` public static int CheckUTF8( byte[] b ) ``` [`VB.NET`] ``` Public Shared Function CheckUTF8 ( _ b As Byte() _ ) As Integer ``` #### Parameters b : input byte array to check #### Return Value Zero if the encoded bytes is invalid UTF-8, or a positive number if the input contains valid UTF-8 data, where the value of the number indicates the nature of the encoded characters: | 0 | Not valid UTF-8 | | --- | --- | | 1 | Valid UTF-8, all chars are 7-bit ASCII | | 2 | Valid UTF-8, contains at least one multi-byte character equivalent to 8-bit ANSI | | 3 | Valid UTF-8, contains at least one multi-byte character that cannot be represented in a single-byte character set | #### Remarks 'Overlong' UTF-8 sequences and illegal surrogates are rejected as invalid. #### See Also VB6/C equivalent: [`CNV_CheckUTF8Bytes`](#CNV_CheckUTF8Bytes) [[Contents](#topofpage)] [[Index](#index)] --- ### Cnv.CheckUTF8File Method Check that a file contains only valid UTF-8 encoded characters. #### Syntax [`C#`] ``` public static int CheckUTF8File( string fileName ) ``` [`VB.NET`] ``` Public Shared Function CheckUTF8File ( _ fileName As String _ ) As Integer ``` #### Parameters fileName : name of file to check #### Return Value Zero if the encoded bytes is invalid UTF-8, or a positive number if the input contains valid UTF-8 data, where the value of the number indicates the nature of the encoded characters: | 0 | Not valid UTF-8 | | --- | --- | | 1 | Valid UTF-8, all chars are 7-bit ASCII | | 2 | Valid UTF-8, contains at least one multi-byte character equivalent to 8-bit ANSI | | 3 | Valid UTF-8, contains at least one multi-byte character that cannot be represented in a single-byte character set | #### Remarks 'Overlong' UTF-8 sequences and illegal surrogates are rejected as invalid. #### See Also VB6/C equivalent: [`CNV_CheckUTF8File`](#CNV_CheckUTF8File) [[Contents](#topofpage)] [[Index](#index)] --- ### Cnv.FromBase58 Method Convert a base58-encoded string to an equivalent array of 8-bit unsigned integers. #### Syntax [`C#`] ``` public static byte[] FromBase58( string s ) ``` [`VB.NET`] ``` Public Shared Function FromBase58 ( _ s As String _ ) As Byte() ``` #### Parameters s : Base58-encoded data #### Return Value Data as array of bytes #### Remarks This uses the "Bitcoin" scheme of base58 encoding where the leading character '1' is reserved for representing an entire leading zero byte. #### See Also VB6/C equivalent: [`CNV_Base58ToBytes`](#CNV_Base58ToBytes) [[Contents](#topofpage)] [[Index](#index)] --- ### Cnv.FromBase64 Method Convert a base64-encoded string to an equivalent array of 8-bit unsigned integers. #### Syntax [`C#`] ``` public static byte[] FromBase64( string s ) ``` [`VB.NET`] ``` Public Shared Function FromBase64 ( _ s As String _ ) As Byte() ``` #### Parameters s : Base64-encoded data #### Return Value Binary data in byte array, or an empty array on error. #### Remarks Whitespace characters are ignored, but other non-base64 characters will cause an error. #### See Also VB6/C equivalent: [`CNV_BytesFromB64Str`](#CNV_BytesFromB64Str) [[Contents](#topofpage)] [[Index](#index)] --- ### Cnv.FromHex Method Convert the specified string representation of a value consisting of hexadecimal (base 16) digits to an equivalent array of 8-bit unsigned integers. #### Syntax [`C#`] ``` public static byte[] FromHex( string s ) ``` [`VB.NET`] ``` Public Shared Function FromHex ( _ s As String _ ) As Byte() ``` #### Parameters s : Hex-encoded string #### Return Value Binary data in byte array, or an empty array on error. #### Remarks Whitespace and ASCII punctuation characters are ignored, but other non-hex characters will cause an error. #### See Also VB6/C equivalent: [`CNV_BytesFromHexStr`](#CNV_BytesFromHexStr) [[Contents](#topofpage)] [[Index](#index)] --- ### Cnv.HexFilter Method Filter non-hexadecimal characters from a string. #### Syntax [`C#`] ``` public static string HexFilter( string s ) ``` [`VB.NET`] ``` Public Shared Function HexFilter ( _ s As String _ ) As String ``` #### Parameters s : Input string to be filtered #### Return Value Filtered string #### See Also VB6/C equivalent: [`CNV_HexFilter`](#CNV_HexFilter) [[Contents](#topofpage)] [[Index](#index)] --- ### Cnv.HexFromBase64 Method Convert base64-encoded data into hexadecimal-encoded data. #### Syntax [`C#`] ``` public static string HexFromBase64( string s ) ``` [`VB.NET`] ``` Public Shared Function HexFromBase64 ( _ s As String _ ) As String ``` #### Parameters s : Base64-encoded data #### Return Value Hex-encoded data [[Contents](#topofpage)] [[Index](#index)] --- ### Cnv.NumFromBytes Method Convert the leftmost four bytes of an array to an unsigned 32-bit integer. #### Syntax [`C#`] ``` public static uint NumFromBytes( byte[] b, Cnv.EndianNess endn ) ``` [`VB.NET`] ``` Public Shared Function NumFromBytes ( _ b As Byte(), _ endn As Cnv.EndianNess _ ) As UInteger ``` #### Parameters b : Byte array to be converted endn : Type: [Cnv.EndianNess](#T_Cnv_EndianNess) Byte order #### Return Value Integer value #### Remarks An array shorter than 4 bytes will be padded on the right with zeros #### Example [`C#`] ``` byte[] b = new byte[4] { 0xde, 0xad, 0xbe, 0xef }; uint nb = Cnv.NumFromBytes(b, Cnv.EndianNess.BigEndian); Console.WriteLine("0x" + nb.ToString("x8")); // 0xdeadbeef uint nl = Cnv.NumFromBytes(b, Cnv.EndianNess.LittleEndian); Console.WriteLine("0x" + nl.ToString("x8")); // 0xefbeadde ``` #### See Also VB6/C equivalent: [`CNV_NumFromBytes`](#CNV_NumFromBytes) [[Contents](#topofpage)] [[Index](#index)] --- ### Cnv.NumToBytes Method Convert a 32-bit integer to an array of 4 bytes. #### Syntax [`C#`] ``` public static byte[] NumToBytes( uint n, Cnv.EndianNess endn ) ``` [`VB.NET`] ``` Public Shared Function NumToBytes ( _ n As UInteger, _ endn As Cnv.EndianNess _ ) As Byte() ``` #### Parameters n : Integer to be converted endn : Type: [Cnv.EndianNess](#T_Cnv_EndianNess) Byte order #### Return Value Byte array containing representation of integer in given order #### Example [`C#`] ``` byte[] bb = Cnv.NumToBytes(0xdeadbeef, Cnv.EndianNess.BigEndian); Console.WriteLine(Cnv.ToHex(bb)); // DEADBEEF byte[] bl = Cnv.NumToBytes(0xdeadbeef, Cnv.EndianNess.LittleEndian); Console.WriteLine(Cnv.ToHex(bl)); // EFBEADDE ``` #### See Also VB6/C equivalent: [`CNV_NumToBytes`](#CNV_NumToBytes) [[Contents](#topofpage)] [[Index](#index)] --- ### Cnv.ReverseBytes Method Reverse the order of a byte array. #### Syntax [`C#`] ``` public static byte[] ReverseBytes( byte[] data ) ``` [`VB.NET`] ``` Public Shared Function ReverseBytes ( _ data As Byte() _ ) As Byte() ``` #### Parameters data : Input data to be reversed #### Return Value Byte array in reverse order #### See Also VB6/C equivalent: [`CNV_ReverseBytes`](#CNV_ReverseBytes) [[Contents](#topofpage)] [[Index](#index)] --- ### Cnv.ShortPathName Method Retrieve the Windows short path form of the specified path. #### Syntax [`C#`] ``` public static string ShortPathName( string pathName ) ``` [`VB.NET`] ``` Public Shared Function ShortPathName ( _ pathName As String _ ) As String ``` #### Parameters pathName : File path name. #### Return Value Windows short path name of file or the empty string if file does not exist. #### Remarks Windows platforms only. The file path must exist. The short path name is guaranteed to be ASCII. #### See Also VB6/C equivalent: [`CNV_ShortPathName`](#CNV_ShortPathName) [[Contents](#topofpage)] [[Index](#index)] --- ### Cnv.StringFromBase64 Method Convert a base64-encoded string into a text string. #### Syntax [`C#`] ``` public static string StringFromBase64( string s ) ``` [`VB.NET`] ``` Public Shared Function StringFromBase64 ( _ s As String _ ) As String ``` #### Parameters s : Base64-encoded data #### Return Value String value #### Remarks Uses the 'Default' encoding for the system's current ANSI code page. This assumes the user knows the resulting characters are all printable. [[Contents](#topofpage)] [[Index](#index)] --- ### Cnv.StringFromHex Method Convert a hexadecimal-encoded string into a text string. #### Syntax [`C#`] ``` public static string StringFromHex( string s ) ``` [`VB.NET`] ``` Public Shared Function StringFromHex ( _ s As String _ ) As String ``` #### Parameters s : Hex-encoded data #### Return Value String value #### Remarks Uses the 'Default' encoding for the system's current ANSI code page, usually code page 1252 (similar to Latin-1). This assumes the user knows the resulting characters are all printable. [[Contents](#topofpage)] [[Index](#index)] --- ### Cnv.ToBase58 Method Convert 8-bit binary data to equivalent base58-encoded string format. #### Syntax [`C#`] ``` public static string ToBase58( byte[] binaryData ) ``` [`VB.NET`] ``` Public Shared Function ToBase58 ( _ binaryData As Byte() _ ) As String ``` #### Parameters binaryData : binary data #### Return Value Base58-encoded string #### Remarks This uses the "Bitcoin" scheme of base58 encoding where the leading character '1' is reserved for representing an entire leading zero byte. #### See Also VB6/C equivalent: [`CNV_Base58FromBytes`](#CNV_Base58FromBytes) [[Contents](#topofpage)] [[Index](#index)] --- ### Cnv.ToBase64 Method (Byte[]) Convert 8-bit binary data to equivalent base64-encoded string format. #### Syntax [`C#`] ``` public static string ToBase64( byte[] binaryData ) ``` [`VB.NET`] ``` Public Shared Function ToBase64 ( _ binaryData As Byte() _ ) As String ``` #### Parameters binaryData : binary data #### Return Value Base64-encoded string #### See Also VB6/C equivalent: [`CNV_B64StrFromBytes`](#CNV_B64StrFromBytes) [[Contents](#topofpage)] [[Index](#index)] --- ### Cnv.ToBase64 Method (String) Convert a string of ANSI characters to equivalent base64-encoded string format. #### Syntax [`C#`] ``` public static string ToBase64( string s ) ``` [`VB.NET`] ``` Public Shared Function ToBase64 ( _ s As String _ ) As String ``` #### Parameters s : String of data to be encoded #### Return Value Base64-encoded data #### Remarks Uses the 'Default' encoding for the system's current ANSI code page #### See Also VB6/C equivalent: [`CNV_B64StrFromBytes`](#CNV_B64StrFromBytes) [[Contents](#topofpage)] [[Index](#index)] --- ### Cnv.ToHex Method (Byte[]) Convert 8-bit binary data to equivalent hexadecimal string format. #### Syntax [`C#`] ``` public static string ToHex( byte[] binaryData ) ``` [`VB.NET`] ``` Public Shared Function ToHex ( _ binaryData As Byte() _ ) As String ``` #### Parameters binaryData : binary data in byte array #### Return Value Hex-encoded string. #### See Also VB6/C equivalent: [`CNV_HexStrFromBytes`](#CNV_HexStrFromBytes) [[Contents](#topofpage)] [[Index](#index)] --- ### Cnv.ToHex Method (String) Converts a string of ANSI characters to equivalent hexadecimal string format #### Syntax [`C#`] ``` public static string ToHex( string s ) ``` [`VB.NET`] ``` Public Shared Function ToHex ( _ s As String _ ) As String ``` #### Parameters s : String of data to be encoded #### Return Value Hex-encoded data #### Remarks Uses the 'Default' encoding for the system's current ANSI code page [[Contents](#topofpage)] [[Index](#index)] --- ### Compr.Compress Method Compress data using zlib compression. #### Syntax [`C#`] ``` public static byte[] Compress( byte[] data ) ``` [`VB.NET`] ``` Public Shared Function Compress ( _ data As Byte() _ ) As Byte() ``` #### Parameters data : Data to be compressed. #### Return Value Compressed data, or an empty array on error. #### See Also VB6/C equivalent: [`COMPR_Compress`](#COMPR_Compress) [[Contents](#topofpage)] [[Index](#index)] --- ### Compr.Uncompress Method Uncompress data using zlib compression. #### Syntax [`C#`] ``` public static byte[] Uncompress( byte[] data ) ``` [`VB.NET`] ``` Public Shared Function Uncompress ( _ data As Byte() _ ) As Byte() ``` #### Parameters data : Compressed data to be uncompressed. #### Return Value Uncompressed data, or an empty array on error. #### Remarks An empty array may also be returned if the original data was the empty array itself. #### See Also VB6/C equivalent: [`COMPR_Uncompress`](#COMPR_Uncompress) [[Contents](#topofpage)] [[Index](#index)] --- ### Ecc.DHSharedSecret Method Compute EC Diffie-Hellman (ECDH) shared secret. #### Syntax [`C#`] ``` public static byte[] DHSharedSecret( string ourIntPrivateKey, string theirIntPublicKey ) ``` [`VB.NET`] ``` Public Shared Function DHSharedSecret ( _ ourIntPrivateKey As String, _ theirIntPublicKey As String _ ) As Byte() ``` #### Parameters ourIntPrivateKey : Our own private key in ephemeral "internal" form. theirIntPublicKey : Other party's public key in "internal" form. #### Return Value The Diffie-Hellman shared secret. #### See Also VB6/C equivalent: [`ECC_DHSharedSecret`](#ECC_DHSharedSecret) [[Contents](#topofpage)] [[Index](#index)] --- ### Ecc.KeyHashCode Method Compute the hash code of an "internal" ECC public or private key string. #### Syntax [`C#`] ``` public static int KeyHashCode( string intKeyString ) ``` [`VB.NET`] ``` Public Shared Function KeyHashCode ( _ intKeyString As String _ ) As Integer ``` #### Parameters intKeyString : Internal key string #### Return Value A 32-bit hash code for the key, or zero on error. #### Remarks Should be the same for a matching private and public key. #### See Also VB6/C equivalent: [`ECC_KeyHashCode`](#ECC_KeyHashCode) [[Contents](#topofpage)] [[Index](#index)] --- ### Ecc.MakeKeys Method Generate an EC public/private key pair and save as two key files. #### Syntax [`C#`] ``` public static int MakeKeys( string publicKeyfile, string privateKeyFile, Ecc.CurveName curveName, string password, Ecc.PbeScheme pbes, string paramString, Ecc.Format fileFormat ) ``` [`VB.NET`] ``` Public Shared Function MakeKeys ( _ publicKeyfile As String, _ privateKeyFile As String, _ curveName As Ecc.CurveName, _ password As String, _ pbes As Ecc.PbeScheme, _ paramString As String, _ fileFormat As Ecc.Format _ ) As Integer ``` #### Parameters publicKeyfile : name of public key file to be created privateKeyFile : name of encrypted private key file to be created curveName : Type: [Ecc.CurveName](#T_Ecc_CurveName) name of elliptic curve password : password to be used for the encrypted key file. pbes : Type: [Ecc.PbeScheme](#T_Ecc_PbeScheme) (optional) Password-based encryption scheme to encrypt private key [default = pbeWithSHAAnd3-KeyTripleDES-CBC] paramString : Optional parameters. A set of attribute name=value pairs separated by a semicolon ";" (see remarks). fileFormat : Type: [Ecc.Format](#T_Ecc_Format) (optional) Format to save file [default = DER binary] #### Return Value Zero if successful or non-zero [error code](#errorcodes) #### Remarks Valid name-value pairs for paramString are: | **count**=integer | To set the iteration count used in the PBKDF2 method, e.g. "count=5000;" [default=2048]. | | --- | --- | | **prf**=hmac-name | To change the HMAC algorithm used in the PBKDF2 method, e.g. "prf=hmacwithSHA256;" [default=hmacwithSHA1]. | | **rngseed**=string | To add some user-supplied entropy for the key generation process, e.g. "rngseed=pqrrr1234xyz;". | Valid values for hmac-name are {hmacWithSHA1|hmacWithSHA224|hmacWithSHA256|hmacWithSHA384|hmacWithSHA512}. #### Example [`C#`] ``` // All default settings... n = Ecc.MakeKeys(pubkeyfile, prikeyfile, Ecc.CurveName.Prime192v1, "password"); // With specialist options... n = Ecc.MakeKeys(pubkeyfile, prikeyfile, Ecc.CurveName.Prime192v1, "password", Ecc.PbeScheme.Pbe_Pbkdf2_aes128_CBC, "count=3999;prf=hmacWithSha256", Ecc.Format.PEM); ``` #### See Also VB6/C equivalent: [`ECC_MakeKeys`](#ECC_MakeKeys) [[Contents](#topofpage)] [[Index](#index)] --- ### Ecc.PublicKeyFromPrivate Method Convert an internal EC private key string into an internal EC public key string. #### Syntax [`C#`] ``` public static string PublicKeyFromPrivate( string internalKey ) ``` [`VB.NET`] ``` Public Shared Function PublicKeyFromPrivate ( _ internalKey As String _ ) As String ``` #### Parameters internalKey : the private key as an internal key string #### Return Value The public key in ephemeral "internal" representation, or the empty string on error #### See Also VB6/C equivalent: [`ECC_PublicKeyFromPrivate`](#ECC_PublicKeyFromPrivate) [[Contents](#topofpage)] [[Index](#index)] --- ### Ecc.QueryKey Method Query an EC key string for selected information. #### Syntax [`C#`] ``` public static string QueryKey( string internalKey, string query ) ``` [`VB.NET`] ``` Public Shared Function QueryKey ( _ internalKey As String, _ query As String _ ) As String ``` #### Parameters internalKey : containing the key as an internal key string query : Query string (case insensitive) #### Return Value String containing the result or an empty string if not found or error. #### Remarks Valid queries are: | "curveName" | Name of the curve. | | --- | --- | | "keyBits" | Number of bits in the key. | | "isPrivate" | "1" if key is a private key; "0" if not. | | "privateKey" | Value of the private key in hex format. | | "publicKey" | Value of the public key in hex format. | #### See Also VB6/C equivalent: [`ECC_QueryKey`](#ECC_QueryKey) [[Contents](#topofpage)] [[Index](#index)] --- ### Ecc.ReadKeyByCurve Method Read an EC key from its hexadecimal representation with options for safe curves. #### Syntax [`C#`] ``` public static string ReadKeyByCurve( string hexKey, Ecc.CurveName curveName, Ecc.KeyType keyType ) ``` [`VB.NET`] ``` Public Shared Function ReadKeyByCurve ( _ hexKey As String, _ curveName As Ecc.CurveName, _ keyType As Ecc.KeyType _ ) As String ``` #### Parameters hexKey : hexadecimal representation of the key, private or public curveName : Type: [Ecc.CurveName](#T_Ecc_CurveName) name of the elliptic curve keyType : Type: [Ecc.KeyType](#T_Ecc_KeyType) (optional) Specify PrivateKey or PublicKey (safe curves Ed25519 and X25519 only, otherwise ignored) #### Return Value The key in ephemeral "internal" representation, or the empty string on error #### Remarks The safe curves Ed25519 and X25519 have the same length for both private and public keys, so, for these safe curves, you **must** specify whether the key value represents a public or a private key. #### See Also VB6/C equivalent: [`ECC_ReadKeyByCurve`](#ECC_ReadKeyByCurve) [[Contents](#topofpage)] [[Index](#index)] --- ### Ecc.ReadPrivateKey Method Read from a file or string containing an EC private key into an "internal" private key string. #### Syntax [`C#`] ``` public static StringBuilder ReadPrivateKey( string keyFileOrString, string password ) ``` [`VB.NET`] ``` Public Shared Function ReadPrivateKey ( _ keyFileOrString As String, _ password As String _ ) As StringBuilder ``` #### Parameters keyFileOrString : Name of private key file or a PEM String containing the key password : Password for private key, if encrypted; or "" if not #### Return Value StringBuilder containing an internal representation of the private key; or an empty StringBuilder if error #### Remarks This returns a StringBuilder, not a string, to allow secure wiping. Use sb.ToString() to obtain a string. Use Wipe.String(sb) to clear. #### See Also VB6/C equivalent: [`ECC_ReadPrivateKey`](#ECC_ReadPrivateKey) [[Contents](#topofpage)] [[Index](#index)] --- ### Ecc.ReadPublicKey Method Read from a file or string containing an EC public key into an "internal" public key string. #### Syntax [`C#`] ``` public static StringBuilder ReadPublicKey( string keyFileOrString ) ``` [`VB.NET`] ``` Public Shared Function ReadPublicKey ( _ keyFileOrString As String _ ) As StringBuilder ``` #### Parameters keyFileOrString : Name of public key file or a PEM String containing the key #### Return Value StringBuilder containing an internal representation of the public key; or an empty StringBuilder if error #### Remarks This returns a StringBuilder, not a string. Use sb.ToString() to obtain a string. #### See Also VB6/C equivalent: [`ECC_ReadPublicKey`](#ECC_ReadPublicKey) [[Contents](#topofpage)] [[Index](#index)] --- ### Ecc.SaveEncKey Method Save an internal EC private key string to an encrypted private key file. #### Syntax [`C#`] ``` public static int SaveEncKey( string outputFile, string internalKey, string password, Ecc.PbeScheme pbes, string paramString, Ecc.Format fileFormat ) ``` [`VB.NET`] ``` Public Shared Function SaveEncKey ( _ outputFile As String, _ internalKey As String, _ password As String, _ pbes As Ecc.PbeScheme, _ paramString As String, _ fileFormat As Ecc.Format _ ) As Integer ``` #### Parameters outputFile : name of key file to be created internalKey : the private key in an internal key string password : the password to be used for the encrypted key file pbes : Type: [Ecc.PbeScheme](#T_Ecc_PbeScheme) Password-based encryption scheme to encrypt private key [default = pbeWithSHAAnd3-KeyTripleDES-CBC] paramString : Optional parameters. A set of attribute name=value pairs separated by a semicolon ";" (see remarks). Set as "" for defaults. fileFormat : Type: [Ecc.Format](#T_Ecc_Format) Format to save file [default = DER binary] #### Return Value Zero if successful or non-zero [error code](#errorcodes) #### Remarks Valid name-value pairs for paramString are: | **count**=integer | To set the iteration count used in the PBKDF2 method, e.g. "count=5000;" [default=2048]. | | --- | --- | | **prf**=hmac-name | To change the HMAC algorithm used in the PBKDF2 method, e.g. "prf=hmacwithSHA256;" [default=hmacwithSHA1]. | Valid values for hmac-name are {hmacWithSHA1|hmacWithSHA224|hmacWithSHA256|hmacWithSHA384|hmacWithSHA512}. #### See Also VB6/C equivalent: [`ECC_SaveEncKey`](#ECC_SaveEncKey) [[Contents](#topofpage)] [[Index](#index)] --- ### Ecc.SaveKey Method Save an internal EC key string (public or private) to an unencrypted key file. #### Syntax [`C#`] ``` public static int SaveKey( string outputFile, string internalKey, Ecc.KeyType keyType, Ecc.Format fileFormat ) ``` [`VB.NET`] ``` Public Shared Function SaveKey ( _ outputFile As String, _ internalKey As String, _ keyType As Ecc.KeyType, _ fileFormat As Ecc.Format _ ) As Integer ``` #### Parameters outputFile : Name of key file to be created internalKey : the private or public EC key in an internal key string keyType : Type: [Ecc.KeyType](#T_Ecc_KeyType) Key structure for private key (ignored for public) fileFormat : Type: [Ecc.Format](#T_Ecc_Format) Format to save file [default = DER binary] #### Return Value If successful, the return value is zero; otherwise it returns a nonzero [error code](#errorcodes) #### See Also VB6/C equivalent: [`ECC_SaveKey`](#ECC_SaveKey) [[Contents](#topofpage)] [[Index](#index)] --- ### General.CompileTime Method Return date and time the core CryptoSys PKI DLL was last compiled. #### Syntax [`C#`] ``` public static string CompileTime() ``` [`VB.NET`] ``` Public Shared Function CompileTime As String ``` #### Return Value Date and time string #### See Also VB6/C equivalent: [`PKI_CompileTime`](#PKI_CompileTime) [[Contents](#topofpage)] [[Index](#index)] --- ### General.ErrorCode Method Return the [error code](#errorcodes) of the *first* error that occurred when calling the last function. #### Syntax [`C#`] ``` public static int ErrorCode() ``` [`VB.NET`] ``` Public Shared Function ErrorCode As Integer ``` #### Return Value Error code #### See Also VB6/C equivalent: [`PKI_ErrorCode`](#PKI_ErrorCode) [[Contents](#topofpage)] [[Index](#index)] --- ### General.ErrorLookup Method Return a description of an [error code](#errorcodes). #### Syntax [`C#`] ``` public static string ErrorLookup( int errCode ) ``` [`VB.NET`] ``` Public Shared Function ErrorLookup ( _ errCode As Integer _ ) As String ``` #### Parameters errCode : Code number #### Return Value Corresponding error message #### See Also VB6/C equivalent: [`PKI_ErrorLookup`](#PKI_ErrorLookup) [[Contents](#topofpage)] [[Index](#index)] --- ### General.FormatErrorMessage Method Return an error message string for the last error. #### Syntax [`C#`] ``` public static string FormatErrorMessage( int errCode, string userMsg ) ``` [`VB.NET`] ``` Public Shared Function FormatErrorMessage ( _ errCode As Integer, _ userMsg As String _ ) As String ``` #### Parameters errCode : Error code returned by last call (*optional*) userMsg : Optional message string #### Return Value Error message as a string Error (errCode) ... [[Contents](#topofpage)] [[Index](#index)] --- ### General.LastError Method Retrieve the last error message set by the toolkit. #### Syntax [`C#`] ``` public static string LastError() ``` [`VB.NET`] ``` Public Shared Function LastError As String ``` #### Return Value Final error message from last call (may be empty) #### See Also VB6/C equivalent: [`PKI_LastError`](#PKI_LastError) [[Contents](#topofpage)] [[Index](#index)] --- ### General.LicenceType Method Return licence type. #### Syntax [`C#`] ``` public static char LicenceType() ``` [`VB.NET`] ``` Public Shared Function LicenceType As Char ``` #### Return Value D=Developer T=Trial #### See Also VB6/C equivalent: [`PKI_LicenceType`](#PKI_LicenceType) [[Contents](#topofpage)] [[Index](#index)] --- ### General.ModuleInfo Method Get additional information about the core DLL module. #### Syntax [`C#`] ``` public static string ModuleInfo() ``` [`VB.NET`] ``` Public Shared Function ModuleInfo As String ``` #### Return Value Additional information, e.g. "Licensed Developer Edition". #### See Also VB6/C equivalent: [`PKI_ModuleInfo`](#PKI_ModuleInfo) [[Contents](#topofpage)] [[Index](#index)] --- ### General.ModuleName Method Return full path name of core CryptoSys PKI DLL module. #### Syntax [`C#`] ``` public static string ModuleName() ``` [`VB.NET`] ``` Public Shared Function ModuleName As String ``` #### Return Value File name. #### Remarks If using the Win32 DLL in the system folder on a 64-bit system, Windows will return "C:\WINDOWS\SYSTEM32\diCrPKI.dll" when the DLL file path is actually "C:\WINDOWS\SYSWOW64\diCrPKI.dll". Use General.Platform() to find out exactly which DLL is being used. #### See Also VB6/C equivalent: [`PKI_ModuleName`](#PKI_ModuleName) [[Contents](#topofpage)] [[Index](#index)] --- ### General.NetVersion Method Return the version of this .NET module. #### Syntax [`C#`] ``` public static string NetVersion() ``` [`VB.NET`] ``` Public Shared Function NetVersion As String ``` #### Return Value Version string, e.g. "20.1.0" [[Contents](#topofpage)] [[Index](#index)] --- ### General.Platform Method Return the platform the core DLL was compiled for. #### Syntax [`C#`] ``` public static string Platform() ``` [`VB.NET`] ``` Public Shared Function Platform As String ``` #### Return Value "Win32" or "X64" #### See Also VB6/C equivalent: [`PKI_Platform`](#PKI_Platform) [[Contents](#topofpage)] [[Index](#index)] --- ### General.PowerUpTests Method Perform FIPS-140-2 start-up tests. #### Syntax [`C#`] ``` public static int PowerUpTests() ``` [`VB.NET`] ``` Public Shared Function PowerUpTests As Integer ``` #### Return Value Zero on success #### See Also VB6/C equivalent: [`PKI_PowerUpTests`](#PKI_PowerUpTests) [[Contents](#topofpage)] [[Index](#index)] --- ### General.Version Method Return the release version of the core CryptoSys PKI DLL as an integer value. #### Syntax [`C#`] ``` public static int Version() ``` [`VB.NET`] ``` Public Shared Function Version As Integer ``` #### Return Value Version number in form Major * 10000 + Minor * 100 + Release. For example, version 3.10.1 would return 31001. #### See Also VB6/C equivalent: [`PKI_Version`](#PKI_Version) [[Contents](#topofpage)] [[Index](#index)] --- ### Hash.BytesFromBytes Method Create hash digest in byte format of byte input. #### Syntax [`C#`] ``` public static byte[] BytesFromBytes( byte[] message, HashAlgorithm hashAlg ) ``` [`VB.NET`] ``` Public Shared Function BytesFromBytes ( _ message As Byte(), _ hashAlg As HashAlgorithm _ ) As Byte() ``` #### Parameters message : Message data in byte format hashAlg : Type: [HashAlgorithm](#T_HashAlgorithm) Hash algorithm to be used #### Return Value Message digest in byte format #### See Also VB6/C equivalent: [`HASH_Bytes`](#HASH_Bytes) [[Contents](#topofpage)] [[Index](#index)] --- ### Hash.BytesFromFile Method Create hash digest of a binary file. #### Syntax [`C#`] ``` public static byte[] BytesFromFile( string fileName, HashAlgorithm hashAlg ) ``` [`VB.NET`] ``` Public Shared Function BytesFromFile ( _ fileName As String, _ hashAlg As HashAlgorithm _ ) As Byte() ``` #### Parameters fileName : Name of file containing message data hashAlg : Type: [HashAlgorithm](#T_HashAlgorithm) Hash algorithm to be used #### Return Value Message digest in byte format #### See Also VB6/C equivalent: [`HASH_File`](#HASH_File) [[Contents](#topofpage)] [[Index](#index)] --- ### Hash.Double Method Create double hash, i.e. hash of hash, in byte format of byte input. #### Syntax [`C#`] ``` public static byte[] Double( byte[] message, HashAlgorithm hashAlg ) ``` [`VB.NET`] ``` Public Shared Function Double ( _ message As Byte(), _ hashAlg As HashAlgorithm _ ) As Byte() ``` #### Parameters message : Message data in byte format hashAlg : Type: [HashAlgorithm](#T_HashAlgorithm) Hash algorithm to be used #### Return Value Message digest HASH(HASH(m)) in byte format #### See Also VB6/C equivalent: [`HASH_Bytes`](#HASH_Bytes) [[Contents](#topofpage)] [[Index](#index)] --- ### Hash.HexFromBytes Method Create hash digest in hex format of byte input. #### Syntax [`C#`] ``` public static string HexFromBytes( byte[] message, HashAlgorithm hashAlg ) ``` [`VB.NET`] ``` Public Shared Function HexFromBytes ( _ message As Byte(), _ hashAlg As HashAlgorithm _ ) As String ``` #### Parameters message : Message data in byte format hashAlg : Type: [HashAlgorithm](#T_HashAlgorithm) Hash algorithm to be used #### Return Value Message digest in hex-encoded format #### See Also VB6/C equivalent: [`HASH_HexFromBytes`](#HASH_HexFromBytes) [[Contents](#topofpage)] [[Index](#index)] --- ### Hash.HexFromFile Method Create hash digest in hex format of a binary file. #### Syntax [`C#`] ``` public static string HexFromFile( string fileName, HashAlgorithm hashAlg ) ``` [`VB.NET`] ``` Public Shared Function HexFromFile ( _ fileName As String, _ hashAlg As HashAlgorithm _ ) As String ``` #### Parameters fileName : Name of file containing message data hashAlg : Type: [HashAlgorithm](#T_HashAlgorithm) Hash algorithm to be used #### Return Value Message digest in hex-encoded format #### See Also VB6/C equivalent: [`HASH_HexFromFile`](#HASH_HexFromFile) [[Contents](#topofpage)] [[Index](#index)] --- ### Hash.HexFromHex Method Create hash digest in hex format of hex-encoded input. #### Syntax [`C#`] ``` public static string HexFromHex( string messageHex, HashAlgorithm hashAlg ) ``` [`VB.NET`] ``` Public Shared Function HexFromHex ( _ messageHex As String, _ hashAlg As HashAlgorithm _ ) As String ``` #### Parameters messageHex : Message data in hex-encoded format hashAlg : Type: [HashAlgorithm](#T_HashAlgorithm) Hash algorithm to be used #### Return Value Message digest in hex-encoded format #### See Also VB6/C equivalent: [`HASH_HexFromHex`](#HASH_HexFromHex) [[Contents](#topofpage)] [[Index](#index)] --- ### Hash.HexFromString Method Create hash digest in hex format of string input. #### Syntax [`C#`] ``` public static string HexFromString( string message, HashAlgorithm hashAlg ) ``` [`VB.NET`] ``` Public Shared Function HexFromString ( _ message As String, _ hashAlg As HashAlgorithm _ ) As String ``` #### Parameters message : Message data string hashAlg : Type: [HashAlgorithm](#T_HashAlgorithm) Hash algorithm to be used #### Return Value Message digest in hex-encoded format #### See Also VB6/C equivalent: [`HASH_HexFromBytes`](#HASH_HexFromBytes) [[Contents](#topofpage)] [[Index](#index)] --- ### Hash.HexFromTextFile Method Create hash digest in hex format of a text file, treating CR-LF (0x13, 0x10) pairs as a single LF (0x10). #### Syntax [`C#`] ``` public static string HexFromTextFile( string fileName, HashAlgorithm hashAlg ) ``` [`VB.NET`] ``` Public Shared Function HexFromTextFile ( _ fileName As String, _ hashAlg As HashAlgorithm _ ) As String ``` #### Parameters fileName : Name of file containing message data hashAlg : Type: [HashAlgorithm](#T_HashAlgorithm) Hash algorithm to be used #### Return Value Message digest in hex format #### Remarks This *should* give the same message digest of a text file on both Unix and Windows systems. #### See Also VB6/C equivalent: [`HASH_HexFromFile`](#HASH_HexFromFile) [[Contents](#topofpage)] [[Index](#index)] --- ### Hash.Length Method Return length of message digest output in bytes. #### Syntax [`C#`] ``` public static int Length( HashAlgorithm hashAlg ) ``` [`VB.NET`] ``` Public Shared Function Length ( _ hashAlg As HashAlgorithm _ ) As Integer ``` #### Parameters hashAlg : Type: [HashAlgorithm](#T_HashAlgorithm) Hash algorithm #### Return Value Length of the hash function output in bytes. #### See Also VB6/C equivalent: [`HASH_Length`](#HASH_Length) [[Contents](#topofpage)] [[Index](#index)] --- ### Hmac.BytesFromBytes Method Create a keyed-hash HMAC in byte format from byte input. #### Syntax [`C#`] ``` public static byte[] BytesFromBytes( byte[] message, byte[] key, HashAlgorithm hashAlg ) ``` [`VB.NET`] ``` Public Shared Function BytesFromBytes ( _ message As Byte(), _ key As Byte(), _ hashAlg As HashAlgorithm _ ) As Byte() ``` #### Parameters message : Message to be signed in byte format key : Key in byte format hashAlg : Type: [HashAlgorithm](#T_HashAlgorithm) Hash algorithm to be used #### Return Value HMAC in byte format #### See Also VB6/C equivalent: [`HMAC_Bytes`](#HMAC_Bytes) [[Contents](#topofpage)] [[Index](#index)] --- ### Hmac.HexFromBytes Method Create a keyed-hash HMAC in hex-encoded format from byte input. #### Syntax [`C#`] ``` public static string HexFromBytes( byte[] message, byte[] key, HashAlgorithm hashAlg ) ``` [`VB.NET`] ``` Public Shared Function HexFromBytes ( _ message As Byte(), _ key As Byte(), _ hashAlg As HashAlgorithm _ ) As String ``` #### Parameters message : Message to be signed in byte format key : Key in byte format hashAlg : Type: [HashAlgorithm](#T_HashAlgorithm) Hash algorithm to be used #### Return Value HMAC in hex-encoded format #### See Also VB6/C equivalent: [`HMAC_HexFromBytes`](#HMAC_HexFromBytes) [[Contents](#topofpage)] [[Index](#index)] --- ### Hmac.HexFromHex Method Create a keyed-hash HMAC in hex-encoded format from hex-encoded input. #### Syntax [`C#`] ``` public static string HexFromHex( string messageHex, string keyHex, HashAlgorithm hashAlg ) ``` [`VB.NET`] ``` Public Shared Function HexFromHex ( _ messageHex As String, _ keyHex As String, _ hashAlg As HashAlgorithm _ ) As String ``` #### Parameters messageHex : Message to be signed in hex-encoded format keyHex : Key in hex-encoded format hashAlg : Type: [HashAlgorithm](#T_HashAlgorithm) Hash algorithm to be used #### Return Value HMAC in hex-encoded format #### See Also VB6/C equivalent: [`HMAC_HexFromHex`](#HMAC_HexFromHex) [[Contents](#topofpage)] [[Index](#index)] --- ### Hpke.DerivePrivateKey Method Derive an EC private key in a deterministic manner from input keying material using the DeriveKeyPair algorithm in RFC9180. #### Syntax [`C#`] ``` public static string DerivePrivateKey( byte[] ikm, Hpke.CurveName curveName, Hpke.OutputOpts opts ) ``` [`VB.NET`] ``` Public Shared Function DerivePrivateKey ( _ ikm As Byte(), _ curveName As Hpke.CurveName, _ opts As Hpke.OutputOpts _ ) As String ``` #### Parameters ikm : Input key material (ikm). This *must* have length in bytes at least as long as the key to be produced. curveName : Type: [Hpke.CurveName](#T_Hpke_CurveName) Curve name opts : Type: [Hpke.OutputOpts](#T_Hpke_OutputOpts) Output options (default=internal key format) #### Return Value Derived private key in string form or an empty string on error. #### Remarks By default the key is output as an ephemeral "internal" key string, which can be used directly with Ecc.SaveKey, Ecc.SaveEncKey, Ecc.PublicKeyFromPrivate, Ecc.DHSharedSecret and Ecc.QueryKey. If opts is set to `OutputOpts.KeyAsHex` then the key is output in serialized hexadecimal form in the same manner as the test vectors in [RFC9180] (without the clamping). The KDF to be used is fixed by the EC curve group as follows: | EC curve | KDF | | --- | --- | | P-256 | HKDF-SHA256 | | P-384 | HKDF-SHA384 | | P-521 | HKDF-SHA512 | | X25519 | HKDF-SHA256 | | X448 | HKDF-SHA512 | #### Example [`C#`] ``` string ikmhex = "7268600d403fce431561aef583ee1613527cff655c1343f29812e66706df3234"; string skhex = Hpke.DerivePrivateKey(Cnv.FromHex(ikmhex), Hpke.CurveName.X25519, Hpke.OutputOpts.KeyAsHex); // 52c4a758a802cd8b936eceea314432798d5baf2d7e9235dc084ab1b9cfa2f736 ``` #### See Also VB6/C equivalent: [`HPKE_DerivePrivateKey`](#HPKE_DerivePrivateKey) [[Contents](#topofpage)] [[Index](#index)] --- ### Hpke.LabeledExpand Method Compute the output of the LabeledExpand function as defined in RFC9180. #### Syntax [`C#`] ``` public static byte[] LabeledExpand( int numBytes, byte[] prk, string label, byte[] info, Hpke.CurveName curveName, Hpke.AeadAlg aeadAlg ) ``` [`VB.NET`] ``` Public Shared Function LabeledExpand ( _ numBytes As Integer, _ prk As Byte(), _ label As String, _ info As Byte(), _ curveName As Hpke.CurveName, _ aeadAlg As Hpke.AeadAlg _ ) As Byte() ``` #### Parameters numBytes : Required number of bytes (L) of output keying material. prk : Pseudorandom key (prk) label : Label string info : Byte string info curveName : Type: [Hpke.CurveName](#T_Hpke_CurveName) ECDH curve used in scheme aeadAlg : Type: [Hpke.AeadAlg](#T_Hpke_AeadAlg) AEAD encryption algorithm used in the scheme or 0 (default) to indicate KDF is being used inside a KEM algorithm. #### Return Value L bytes of output keying material. #### Remarks The LabeledExpand function is defined in section 4 of [RFC9180]. It uses the "expand" stage of the HKDF function [RFC5869]. The ECDH curve group used in the scheme must be specified, which automatically fixes the KDF and associated HMAC algorithm to be used. #### Example [`C#`] ``` int Nk = 16; // key = LabeledExpand(secret, 'key', key_schedule_context, Nk) byte[] key = Hpke.LabeledExpand(Nk, Cnv.FromHex("12fff91991e93b48de37e7daddb52981084bd8aa64289c3788471d9a9712f397"), "key", Cnv.FromHex("00725611c9d98c07c03f60095cd32d400d8347d45ed67097bbad50fc56da742d07cb6cffde367bb0565ba28bb02c90744a20f5ef37f30523526106f637abb05449"), Hpke.CurveName.X25519, Hpke.AeadAlg.Aes_128_Gcm); // 4531685d41d65f03dc48f6b8302c05b0 ``` #### See Also VB6/C equivalent: [`HPKE_LabeledExpand`](#HPKE_LabeledExpand) [[Contents](#topofpage)] [[Index](#index)] --- ### Hpke.LabeledExtract Method Compute the output of the LabeledExtract function as defined in RFC9180. #### Syntax [`C#`] ``` public static byte[] LabeledExtract( byte[] salt, string label, byte[] ikm, Hpke.CurveName curveName, Hpke.AeadAlg aeadAlg ) ``` [`VB.NET`] ``` Public Shared Function LabeledExtract ( _ salt As Byte(), _ label As String, _ ikm As Byte(), _ curveName As Hpke.CurveName, _ aeadAlg As Hpke.AeadAlg _ ) As Byte() ``` #### Parameters salt : Byte string salt label : Label string ikm : Input keying material (ikm) curveName : Type: [Hpke.CurveName](#T_Hpke_CurveName) ECDH curve used in scheme aeadAlg : Type: [Hpke.AeadAlg](#T_Hpke_AeadAlg) AEAD encryption algorithm used in the scheme or 0 (default) to indicate KDF is being used inside a KEM algorithm. #### Return Value A pseudorandom key of fixed length Nh bytes. #### Remarks The LabeledExtract function is defined in section 4 of [RFC9180]. It uses the "extract" stage of the HKDF function [RFC5869] and outputs a fixed value of bytes equal to the length (Nh) of the underlying HMAC function used by the KDF algorithm. The ECDH curve group used in the scheme must be specified, which automatically fixes the KDF and associated HMAC algorithm to be used. #### Example [`C#`] ``` // Used inside KEM string ikmhex = "7268600d403fce431561aef583ee1613527cff655c1343f29812e66706df3234"; Console.WriteLine(Cnv.ToHex(Hpke.LabeledExtract(null, "dkp_prk", Cnv.FromHex(ikmhex), Hpke.CurveName.X25519))); // 7B8BFE1D6F3D0CB45C585E133299C64AC998BF46CAF2DC13BA874F23413EC23A // Used outside KEM Console.WriteLine(Cnv.ToHex(Hpke.LabeledExtract(null, "psk_id_hash", null, Hpke.CurveName.X25519, Hpke.AeadAlg.Aes_128_Gcm))); // 725611C9D98C07C03F60095CD32D400D8347D45ED67097BBAD50FC56DA742D07 ``` #### See Also VB6/C equivalent: [`HPKE_LabeledExtract`](#HPKE_LabeledExtract) [[Contents](#topofpage)] [[Index](#index)] --- ### Kdf.Bytes Method Generate a key-encryption key (KEK) from input keying material (IKM) using a key derivation function (KDF). #### Syntax [`C#`] ``` public static byte[] Bytes( int dkLen, byte[] ikm, Kdf.KdfAlg kdfAlg, Kdf.HashAlg hashAlg, byte[] sharedInfo, string paramString ) ``` [`VB.NET`] ``` Public Shared Function Bytes ( _ dkLen As Integer, _ ikm As Byte(), _ kdfAlg As Kdf.KdfAlg, _ hashAlg As Kdf.HashAlg, _ sharedInfo As Byte(), _ paramString As String _ ) As Byte() ``` #### Parameters dkLen : Required length of output key material in bytes. ikm : Input key material/shared secret. kdfAlg : Type: [Kdf.KdfAlg](#T_Kdf_KdfAlg) Key derivation function to use. hashAlg : Type: [Kdf.HashAlg](#T_Kdf_HashAlg) Hash algorithm to use with the key derivation function (default is SHA-1) sharedInfo : SharedInfo (optional) paramString : Optional parameters. Set as "" for defaults. Pass attribute-value salt= to set the optional salt parameter for the HKDF algorithm, e.g. "salt=606162636465666768696a6b6c6d6e6f;" #### Return Value Output key material (KEK). #### See Also VB6/C equivalent: [`KDF_Bytes`](#KDF_Bytes) [[Contents](#topofpage)] [[Index](#index)] --- ### Kdf.ForCms Method Generate a key-encryption key (KEK) for ECDH key exchange in a CMS EnvelopedData object. #### Syntax [`C#`] ``` public static byte[] ForCms( byte[] zz, Kdf.KeyWrapAlg keyWrapAlg, Kdf.KdfAlg kdfAlg, Kdf.HashAlg hashAlg, byte[] ukm ) ``` [`VB.NET`] ``` Public Shared Function ForCms ( _ zz As Byte(), _ keyWrapAlg As Kdf.KeyWrapAlg, _ kdfAlg As Kdf.KdfAlg, _ hashAlg As Kdf.HashAlg, _ ukm As Byte() _ ) As Byte() ``` #### Parameters zz : Input key material/shared secret value (denoted variously as ZZ/Z/K/IKM) keyWrapAlg : Type: [Kdf.KeyWrapAlg](#T_Kdf_KeyWrapAlg) Key wrap algorithm (required, cannot be Default) kdfAlg : Type: [Kdf.KdfAlg](#T_Kdf_KdfAlg) Key derivation function to use. hashAlg : Type: [Kdf.HashAlg](#T_Kdf_HashAlg) Hash algorithm to use with the key derivation function (default is SHA-1) ukm : Optional user key material (ukm) #### Return Value Output key material (KEK). #### Remarks This is a specialist function using the key definition algorithms described in [RFC5753] and [RFC8418] when used for key agreement with ECDH in a CMS EnvelopedData object. The key-encryption key is derived using the ECC-CMS-SharedInfo type, described in section 7.2 of [RFC5753]. #### See Also VB6/C equivalent: [`KDF_ForCms`](#KDF_ForCms) [[Contents](#topofpage)] [[Index](#index)] --- ### Ocsp.MakeRequest Method Create an Online Certification Status Protocol (OCSP) request as a base64 string. #### Syntax [`C#`] ``` public static string MakeRequest( string issuerCert, string certFileOrSerialNumber, HashAlgorithm hashAlg ) ``` [`VB.NET`] ``` Public Shared Function MakeRequest ( _ issuerCert As String, _ certFileOrSerialNumber As String, _ hashAlg As HashAlgorithm _ ) As String ``` #### Parameters issuerCert : name of issuer's X.509 certificate file (or base64 representation) certFileOrSerialNumber : either the name of X.509 certificate file to be checked or its serial number in hexadecimal format preceded by #x hashAlg : Type: [HashAlgorithm](#T_HashAlgorithm) Hash algorithm to be used [default = SHA-1] #### Return Value A base64 string suitable for an OCSP request to an Online Certificate Status Manager or an empty string on error. #### Remarks The issuer's X.509 certficate must be specified. The certificate to be checked can either be specified directly as a filename or as a serialNumber in hexadecimal format preceded by "#x", e.g. "#x01deadbeef". If the latter format is used, it must be in hexadecimal format, so the serial number 10 would be passed as "#x0a". It is an error (NO_MATCH_ERROR) if the issuer's name of the certificate to be checked does not match the subject name of the issuer's certificate. #### See Also VB6/C equivalent: [`OCSP_MakeRequest`](#OCSP_MakeRequest) [[Contents](#topofpage)] [[Index](#index)] --- ### Ocsp.ReadResponse Method Read a response to an Online Certification Status Protocol (OCSP) request and outputs the main results in text form. #### Syntax [`C#`] ``` public static string ReadResponse( string responseFile, string issuerCert ) ``` [`VB.NET`] ``` Public Shared Function ReadResponse ( _ responseFile As String, _ issuerCert As String _ ) As String ``` #### Parameters responseFile : name of the file containing the response data in BER format. issuerCert : (optional) name of issuer's X.509 certificate file (or base64 representation) #### Return Value A text string outlining the main results in the response data or an empty string on error. #### Remarks Note that a revoked certificate will still result in a "Successful response", so check the CertStatus. The issuer's X.509 certficate issuerCert is optional. If provided, it will be used to check the signature on the OCSP reponse and and an error will result if the signature is not valid. **CAUTION:** For some CAs (e.g. VeriSign) the key used to sign the OCSP response is not the same as the key in the issuer's certificate, so specifying the issuer's certificate in this case will result in a signature error. If you can separately obtain the certificate used to sign the OCSP response, then specify this as the issuerCert; otherwise leave as the empty string "". #### See Also VB6/C equivalent: [`OCSP_ReadResponse`](#OCSP_ReadResponse) [[Contents](#topofpage)] [[Index](#index)] --- ### Pbe.Kdf2 Method (Int32, Byte[], Byte[], Int32, HashAlgorithm) Derive a key of any length from a password using the PBKDF2 algorithm from PKCS #5 v2.1. #### Syntax [`C#`] ``` public static byte[] Kdf2( int dkLen, byte[] pwdBytes, byte[] salt, int count, HashAlgorithm hashAlg ) ``` [`VB.NET`] ``` Public Shared Function Kdf2 ( _ dkLen As Integer, _ pwdBytes As Byte(), _ salt As Byte(), _ count As Integer, _ hashAlg As HashAlgorithm _ ) As Byte() ``` #### Parameters dkLen : Required length of key in bytes pwdBytes : Password in byte format salt : Salt in byte format count : Iteration count hashAlg : Type: [HashAlgorithm](#T_HashAlgorithm) Hash algorithm to use in HMAC PRF (default is SHA-1) #### Return Value Key in byte[] format #### See Also VB6/C equivalent: [`PBE_Kdf2`](#PBE_Kdf2) [[Contents](#topofpage)] [[Index](#index)] --- ### Pbe.Kdf2 Method (Int32, String, String, Int32, HashAlgorithm) Derive a key in hex format of any length from a password with the salt in hex format. #### Syntax [`C#`] ``` public static string Kdf2( int dkLen, string pwdStr, string saltHex, int count, HashAlgorithm hashAlg ) ``` [`VB.NET`] ``` Public Shared Function Kdf2 ( _ dkLen As Integer, _ pwdStr As String, _ saltHex As String, _ count As Integer, _ hashAlg As HashAlgorithm _ ) As String ``` #### Parameters dkLen : Required length of key in bytes pwdStr : Password saltHex : Salt in hex format count : Iteration count hashAlg : Type: [HashAlgorithm](#T_HashAlgorithm) Hash algorithm to use in HMAC PRF (default is SHA-1) #### Return Value Key in hex format #### See Also VB6/C equivalent: [`PBE_Kdf2Hex`](#PBE_Kdf2Hex) [[Contents](#topofpage)] [[Index](#index)] --- ### Pbe.Scrypt Method (Int32, Byte[], Byte[], Int32, Int32, Int32) Derives a key of any length from a password using the SCRYPT algorithm. #### Syntax [`C#`] ``` public static byte[] Scrypt( int dkLen, byte[] pwdBytes, byte[] salt, int N, int r, int p ) ``` [`VB.NET`] ``` Public Shared Function Scrypt ( _ dkLen As Integer, _ pwdBytes As Byte(), _ salt As Byte(), _ N As Integer, _ r As Integer, _ p As Integer _ ) As Byte() ``` #### Parameters dkLen : Required length of key in bytes pwdBytes : Password encoded in byte format salt : Salt in byte format N : CPU/Memory cost parameter, a number greater than one and a power of 2. r : Block size r p : Parallelization parameter p #### Return Value Key in byte[] format #### See Also VB6/C equivalent: [`PBE_Scrypt`](#PBE_Scrypt) [[Contents](#topofpage)] [[Index](#index)] --- ### Pbe.Scrypt Method (Int32, String, String, Int32, Int32, Int32) Derives a key in hex format from a password with the salt in hex format #### Syntax [`C#`] ``` public static string Scrypt( int dkLen, string pwdStr, string saltHex, int N, int r, int p ) ``` [`VB.NET`] ``` Public Shared Function Scrypt ( _ dkLen As Integer, _ pwdStr As String, _ saltHex As String, _ N As Integer, _ r As Integer, _ p As Integer _ ) As String ``` #### Parameters dkLen : Required length of key in bytes pwdStr : Password (normal text) saltHex : Salt in hex format N : CPU/Memory cost parameter, a number greater than one and a power of 2. r : Block size r p : Parallelization parameter p #### Return Value Key in hex format #### Remarks Password pwdStr is normal text, not hexadecimal #### Example [`C#`] ``` string keyHex = Pbe.Scrypt(64, "password", "4E61436C", 1024, 8, 16); ``` #### See Also VB6/C equivalent: [`PBE_ScryptHex`](#PBE_ScryptHex) [[Contents](#topofpage)] [[Index](#index)] --- ### Pem.FileFromBinFile Method Create a PEM file from a binary file with option for line endings. #### Syntax [`C#`] ``` public static int FileFromBinFile( string fileToMake, string fileIn, string header, int lineLen, bool unixEOL ) ``` [`VB.NET`] ``` Public Shared Function FileFromBinFile ( _ fileToMake As String, _ fileIn As String, _ header As String, _ lineLen As Integer, _ unixEOL As Boolean _ ) As Integer ``` #### Parameters fileToMake : Name of PEM file to create fileIn : Name of input binary file header : Header to be used. Leave empty to omit the PEM header and footer. lineLen : Maximum length of a line in the resulting PEM file [default = 64 characters] unixEOL : Set true for Unix/SSL LF line endings [optional, default = Windows CR-LF endings] #### Return Value Zero if successful; otherwise it returns an [error code](#errorcodes) #### See Also VB6/C equivalent: [`PEM_FileFromBinFile`](#PEM_FileFromBinFile) [[Contents](#topofpage)] [[Index](#index)] --- ### Pem.FileToBinFile Method Convert the contents of a PEM file into a binary file. #### Syntax [`C#`] ``` public static int FileToBinFile( string fileToMake, string fileIn ) ``` [`VB.NET`] ``` Public Shared Function FileToBinFile ( _ fileToMake As String, _ fileIn As String _ ) As Integer ``` #### Parameters fileToMake : Name of binary file to create. fileIn : Name of input PEM file #### Return Value Zero if successful; otherwise it returns an [error code](#errorcodes) #### See Also VB6/C equivalent: [`PEM_FileToBinFile`](#PEM_FileToBinFile) [[Contents](#topofpage)] [[Index](#index)] --- ### Pfx.MakeFile Method Create a PFX (PKCS-12) file from an X.509 certificate and (optional) encrypted private key file with advanced options. #### Syntax [`C#`] ``` public static int MakeFile( string fileToMake, string certFile, string privateKeyFile, string password, string friendlyName, Pfx.Options pfxOptions ) ``` [`VB.NET`] ``` Public Shared Function MakeFile ( _ fileToMake As String, _ certFile As String, _ privateKeyFile As String, _ password As String, _ friendlyName As String, _ pfxOptions As Pfx.Options _ ) As Integer ``` #### Parameters fileToMake : name of output file to be created certFile : filename of the subject's X.509 certificate (required) privateKeyFile : filename of the subject's encrypted private key in pkcs-8 format (optional) password : password for private key file and new PFX file friendlyName : friendly name identification for the subject (optional) pfxOptions : Type: [Pfx.Options](#T_Pfx_Options) Specialist options #### Return Value Zero if successful or a non-zero [error code](#errorcodes). #### Remarks The default behaviour is to encrypt the certificate using "weak" 40-bit RC2 and the private key (if provided) using "standard" Triple DES (pbeWithSHAAnd3-KeyTripleDES-CBC). #### See Also VB6/C equivalent: [`PFX_MakeFile`](#PFX_MakeFile) [[Contents](#topofpage)] [[Index](#index)] --- ### Pfx.SignatureIsValid Method Verify the MacData signature in a PKCS-12 file. #### Syntax [`C#`] ``` public static bool SignatureIsValid( string fileName, string password ) ``` [`VB.NET`] ``` Public Shared Function SignatureIsValid ( _ fileName As String, _ password As String _ ) As Boolean ``` #### Parameters fileName : Name of PKCS-12 file to be checked password : password for file #### Return Value true if signature is OK #### See Also VB6/C equivalent: [`PFX_VerifySig`](#PFX_VerifySig) [[Contents](#topofpage)] [[Index](#index)] --- ### Prf.Bytes Method Generate output bytes using a pseudorandom function (PRF). #### Syntax [`C#`] ``` public static byte[] Bytes( int numBytes, byte[] message, byte[] key, Prf.Alg prfAlg, string customStr ) ``` [`VB.NET`] ``` Public Shared Function Bytes ( _ numBytes As Integer, _ message As Byte(), _ key As Byte(), _ prfAlg As Prf.Alg, _ customStr As String _ ) As Byte() ``` #### Parameters numBytes : Required number of output bytes. message : Input message data. key : Key. prfAlg : Type: [Prf.Alg](#T_Prf_Alg) PRF algorithm. customStr : Customization string (optional). #### Return Value Output data in byte array. #### See Also VB6/C equivalent: [`PRF_Bytes`](#PRF_Bytes) [[Contents](#topofpage)] [[Index](#index)] --- ### Pwd.Prompt Method Open a dialog box to receive a password with user-supplied prompt. #### Syntax [`C#`] ``` public static string Prompt( int maxChars, string caption, string prompt ) ``` [`VB.NET`] ``` Public Shared Function Prompt ( _ maxChars As Integer, _ caption As String, _ prompt As String _ ) As String ``` #### Parameters maxChars : Maximum characters expected in password caption : Caption for dialog window prompt : Wording for prompt (optional, default="Enter password:") #### Return Value String containing password or Empty string if user cancels #### See Also VB6/C equivalent: [`PWD_Prompt`](#PWD_Prompt) [[Contents](#topofpage)] [[Index](#index)] --- ### Rng.Bytes Method (Int32) Generate an array of random bytes. #### Syntax [`C#`] ``` public static byte[] Bytes( int numBytes ) ``` [`VB.NET`] ``` Public Shared Function Bytes ( _ numBytes As Integer _ ) As Byte() ``` #### Parameters numBytes : Required number of random bytes #### Return Value Array of random bytes #### See Also VB6/C equivalent: [`RNG_Bytes`](#RNG_Bytes) [[Contents](#topofpage)] [[Index](#index)] --- ### Rng.Bytes Method (Int32, Byte[]) Generate an array of random bytes with user-supplied entropy. #### Syntax [`C#`] ``` public static byte[] Bytes( int numBytes, byte[] arrSeed ) ``` [`VB.NET`] ``` Public Shared Function Bytes ( _ numBytes As Integer, _ arrSeed As Byte() _ ) As Byte() ``` #### Parameters numBytes : Required number of random bytes arrSeed : User-supplied entropy in byte format #### Return Value Array of random bytes #### See Also VB6/C equivalent: [`RNG_Bytes`](#RNG_Bytes) [[Contents](#topofpage)] [[Index](#index)] --- ### Rng.Bytes Method (Int32, String) Generate an array of random bytes with user-supplied entropy. #### Syntax [`C#`] ``` public static byte[] Bytes( int numBytes, string seedStr ) ``` [`VB.NET`] ``` Public Shared Function Bytes ( _ numBytes As Integer, _ seedStr As String _ ) As Byte() ``` #### Parameters numBytes : Required number of random bytes seedStr : User-supplied entropy in string format #### Return Value Array of random bytes #### See Also VB6/C equivalent: [`RNG_Bytes`](#RNG_Bytes) [[Contents](#topofpage)] [[Index](#index)] --- ### Rng.BytesWithPrompt Method (Int32, Rng.Strength) Generate an array of random bytes with a prompt for random keyboard input. #### Syntax [`C#`] ``` public static byte[] BytesWithPrompt( int numBytes, Rng.Strength strength ) ``` [`VB.NET`] ``` Public Shared Function BytesWithPrompt ( _ numBytes As Integer, _ strength As Rng.Strength _ ) As Byte() ``` #### Parameters numBytes : Required number of random bytes strength : Type: [Rng.Strength](#T_Rng_Strength) Estimated security strength (default=112 bits) #### Return Value Array of random bytes #### See Also VB6/C equivalent: [`RNG_BytesWithPrompt`](#RNG_BytesWithPrompt) [[Contents](#topofpage)] [[Index](#index)] --- ### Rng.BytesWithPrompt Method (Int32, String, Rng.Strength) Generate an array of random bytes with a prompt for random keyboard input. #### Syntax [`C#`] ``` public static byte[] BytesWithPrompt( int numBytes, string prompt, Rng.Strength strength ) ``` [`VB.NET`] ``` Public Shared Function BytesWithPrompt ( _ numBytes As Integer, _ prompt As String, _ strength As Rng.Strength _ ) As Byte() ``` #### Parameters numBytes : Required number of random bytes prompt : Alternative prompt. Set as an empty string "" for the default prompt. strength : Type: [Rng.Strength](#T_Rng_Strength) Required security strength #### Return Value Array of random bytes #### See Also VB6/C equivalent: [`RNG_BytesWithPrompt`](#RNG_BytesWithPrompt) [[Contents](#topofpage)] [[Index](#index)] --- ### Rng.Guid Method Generate a random 36-character Global Unique IDentifier (GUID) string according to [RFC4122]. #### Syntax [`C#`] ``` public static string Guid() ``` [`VB.NET`] ``` Public Shared Function Guid As String ``` #### Return Value String of the form "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" where 'x' is a hexadecimal digit [0-9a-f]. #### See Also VB6/C equivalent: [`RNG_Guid`](#RNG_Guid) [[Contents](#topofpage)] [[Index](#index)] --- ### Rng.Initialize Method Initialize the RNG generator with a seed file. #### Syntax [`C#`] ``` public static bool Initialize( string seedFile ) ``` [`VB.NET`] ``` Public Shared Function Initialize ( _ seedFile As String _ ) As Boolean ``` #### Parameters seedFile : Full path name of seed file #### Return Value true if successful; false if fails #### Remarks If the seed file does not exist, it will be created (with any available entropy). #### See Also VB6/C equivalent: [`RNG_Initialize`](#RNG_Initialize) [[Contents](#topofpage)] [[Index](#index)] --- ### Rng.InitializeEx Method Query and initialize the RNG generator using Intel(R) DRNG, if available. #### Syntax [`C#`] ``` public static int InitializeEx( Rng.Options opts ) ``` [`VB.NET`] ``` Public Shared Function InitializeEx ( _ opts As Rng.Options _ ) As Integer ``` #### Parameters opts : Type: [Rng.Options](#T_Rng_Options) Specify Rng.Options.NoIntelDrng to explicitly *turn off* support. #### Return Value Support status for Intel(R) DRNG. If available, then a positive value (1,2,3); else a negative [error code](#errorcodes). #### See Also VB6/C equivalent: [`RNG_Initialize`](#RNG_Initialize) [[Contents](#topofpage)] [[Index](#index)] --- ### Rng.MakeSeedFile Method Create a new seed file suitable for use with Rng.Initialize. #### Syntax [`C#`] ``` public static bool MakeSeedFile( string seedFile, Rng.Strength strength ) ``` [`VB.NET`] ``` Public Shared Function MakeSeedFile ( _ seedFile As String, _ strength As Rng.Strength _ ) As Boolean ``` #### Parameters seedFile : Name of seed file to be created strength : Type: [Rng.Strength](#T_Rng_Strength) Estimated security strength (default=112 bits) #### Return Value true if successful; false if fails #### Remarks Any existing file will be overwritten. #### See Also VB6/C equivalent: [`RNG_MakeSeedFile`](#RNG_MakeSeedFile) [[Contents](#topofpage)] [[Index](#index)] --- ### Rng.Number Method Generate a random number (integer) in a given range. #### Syntax [`C#`] ``` public static int Number( int lower, int upper ) ``` [`VB.NET`] ``` Public Shared Function Number ( _ lower As Integer, _ upper As Integer _ ) As Integer ``` #### Parameters lower : lower value of range upper : upper value of range #### Return Value Random integer x: lower <= x <= upper #### See Also VB6/C equivalent: [`RNG_Number`](#RNG_Number) [[Contents](#topofpage)] [[Index](#index)] --- ### Rng.Octet Method Generate a single random octet (byte). #### Syntax [`C#`] ``` public static byte Octet() ``` [`VB.NET`] ``` Public Shared Function Octet As Byte ``` #### Return Value Single byte value randomly chosen between 0 and 255 #### See Also VB6/C equivalent: [`RNG_Number`](#RNG_Number) [[Contents](#topofpage)] [[Index](#index)] --- ### Rng.Test Method Carry out a NIST SP800-90 health check and FIPS140-2 statistical tests on the random number generator. #### Syntax [`C#`] ``` public static bool Test( string resultFile ) ``` [`VB.NET`] ``` Public Shared Function Test ( _ resultFile As String _ ) As Boolean ``` #### Parameters resultFile : Name of results file to be created, or null not to create a results file. #### Return Value true if successful; false if fails #### Remarks Any existing file will be overwritten. #### See Also VB6/C equivalent: [`RNG_Test`](#RNG_Test) [[Contents](#topofpage)] [[Index](#index)] --- ### Rng.TestDrbgvs Method Test the RNG for conformance to NIST SP800-90A using the relevant test specified in DRBGVS. #### Syntax [`C#`] ``` public static string TestDrbgvs( int returnedBitsLen, string entropyInput, string nonce, string personalizationString, string additionalInput1, string entropyReseed, string additionalInputReseed, string additionalInput2 ) ``` [`VB.NET`] ``` Public Shared Function TestDrbgvs ( _ returnedBitsLen As Integer, _ entropyInput As String, _ nonce As String, _ personalizationString As String, _ additionalInput1 As String, _ entropyReseed As String, _ additionalInputReseed As String, _ additionalInput2 As String _ ) As String ``` #### Parameters returnedBitsLen : Number of bits to be returned from each call to the generate function in the test entropyInput : the EntropyInput value in hex format nonce : the Nonce value in hex format personalizationString : the PersonalizationString value in hex format additionalInput1 : the first AdditionalInput value in hex format entropyReseed : the EntropyReseed value in hex format additionalInputReseed : the AdditionalInputReseed value in hex format additionalInput2 : the second AdditionalInput value in hex format #### Return Value the ReturnedBits as a string in hexadecimal format #### Remarks The test procedure, the input values and the expected output are described in the DRBGVS document. The relevant DRBG mechanism is HMAC_DRBG SHA-512 without prediction resistance. Use the empty string "" to pass a zero-length input. All hex strings must have an even number of characters. #### See Also VB6/C equivalent: [`RNG_TestDRBGVS`](#RNG_TestDRBGVS) [[Contents](#topofpage)] [[Index](#index)] --- ### Rng.UpdateSeedFile Method Update the RNG seed file. #### Syntax [`C#`] ``` public static bool UpdateSeedFile( string seedFile ) ``` [`VB.NET`] ``` Public Shared Function UpdateSeedFile ( _ seedFile As String _ ) As Boolean ``` #### Parameters seedFile : Full path name of seed file #### Return Value true if successful; false if fails #### Remarks The seed file must be writable. If it does not exist it will be created (with any available entropy). Any existing file of the same name will be overwritten without warning. #### See Also VB6/C equivalent: [`RNG_UpdateSeedFile`](#RNG_UpdateSeedFile) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.CheckKey Method (String) Check the validity of an "internal" RSA public or private key. #### Syntax [`C#`] ``` public static int CheckKey( string intKeyString ) ``` [`VB.NET`] ``` Public Shared Function CheckKey ( _ intKeyString As String _ ) As Integer ``` #### Parameters intKeyString : Internal key string #### Return Value 0=valid private key, 1=valid publickey, or negative [error code](#errorcodes) #### Remarks A private key is also validated for consistency. #### See Also VB6/C equivalent: [`RSA_CheckKey`](#RSA_CheckKey) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.CheckKey Method (StringBuilder) Check the validity of an "internal" RSA public or private key. #### Syntax [`C#`] ``` public static int CheckKey( StringBuilder sbKeyString ) ``` [`VB.NET`] ``` Public Shared Function CheckKey ( _ sbKeyString As StringBuilder _ ) As Integer ``` #### Parameters sbKeyString : Internal key string #### Return Value 0=valid private key, 1=valid publickey, or negative [error code](#errorcodes) #### Remarks A private key is also validated for consistency. #### See Also VB6/C equivalent: [`RSA_CheckKey`](#RSA_CheckKey) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.DecodeDigestForSignature Method Decode an encoded message for signature. #### Syntax [`C#`] ``` public static byte[] DecodeDigestForSignature( byte[] data, bool getFullDigestInfo ) ``` [`VB.NET`] ``` Public Shared Function DecodeDigestForSignature ( _ data As Byte(), _ getFullDigestInfo As Boolean _ ) As Byte() ``` #### Parameters data : Encoded message for signature getFullDigestInfo : (optional) If true, extract the full DigestInfo; otherwise just extract the message digest itself #### Return Value Decoded data or an empty array on error #### Remarks Only EMSA-PKCS1-v1_5 is supported in this function. #### See Also VB6/C equivalent: [`RSA_DecodeMsg`](#RSA_DecodeMsg) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.DecodeMsgForEncryption Method Decode a message for encryption. #### Syntax [`C#`] ``` public static byte[] DecodeMsgForEncryption( byte[] data, Rsa.EME method ) ``` [`VB.NET`] ``` Public Shared Function DecodeMsgForEncryption ( _ data As Byte(), _ method As Rsa.EME _ ) As Byte() ``` #### Parameters data : Encoded message method : Type: [Rsa.EME](#T_Rsa_EME) Encoding method used #### Return Value Decoded message #### See Also VB6/C equivalent: [`RSA_DecodeMsg`](#RSA_DecodeMsg) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.DecodeMsgIso9796 Method Decode a message padded using ISO/IEC 9796-1 formatting. #### Syntax [`C#`] ``` public static byte[] DecodeMsgIso9796( byte[] data, int keyBits ) ``` [`VB.NET`] ``` Public Shared Function DecodeMsgIso9796 ( _ data As Byte(), _ keyBits As Integer _ ) As Byte() ``` #### Parameters data : encoded message for signature keyBits : exact length of key in *bits* #### Return Value Recovered message or an empty array on error #### See Also VB6/C equivalent: [`RSA_DecodeMsg`](#RSA_DecodeMsg) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.Decrypt Method Decrypt a message encrypted using an RSA encryption scheme. #### Syntax [`C#`] ``` public static byte[] Decrypt( byte[] data, string privateKeyFile, string password, Rsa.EME method, Rsa.HashAlg hashAlg, Rsa.AdvOptions advOpts ) ``` [`VB.NET`] ``` Public Shared Function Decrypt ( _ data As Byte(), _ privateKeyFile As String, _ password As String, _ method As Rsa.EME, _ hashAlg As Rsa.HashAlg, _ advOpts As Rsa.AdvOptions _ ) As Byte() ``` #### Parameters data : Data to be decrypted (*must* be exactly the same length as the key modulus size). privateKeyFile : Name of the private key file, or a string containing the key in PEM format, or a valid internal private key string. password : Password for encrypted private key, or "" if password is not required. method : Type: [Rsa.EME](#T_Rsa_EME) Encoding method [optional, default = EME.PKCSv1_5] hashAlg : Type: [Rsa.HashAlg](#T_Rsa_HashAlg) Hash function for EME-OAEP encoding, otherwise ignored. advOpts : Type: [Rsa.AdvOptions](#T_Rsa_AdvOptions) Advanced options for EME-OEAP only. #### Return Value Decrypted data. #### Remarks For RSA-OAEP you must set the correct options to match the parameters used for the encryption. #### See Also VB6/C equivalent: [`RSA_Decrypt`](#RSA_Decrypt) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.EncodeDigestForSignature Method Encode a message digest for signature. #### Syntax [`C#`] ``` public static byte[] EncodeDigestForSignature( int keyBytes, byte[] digest, HashAlgorithm hashAlg ) ``` [`VB.NET`] ``` Public Shared Function EncodeDigestForSignature ( _ keyBytes As Integer, _ digest As Byte(), _ hashAlg As HashAlgorithm _ ) As Byte() ``` #### Parameters keyBytes : Number of bytes in the key digest : Digest of message hashAlg : Type: [HashAlgorithm](#T_HashAlgorithm) Message digest algorithm used to create digest #### Return Value Encoded block #### Remarks Only EMSA-PKCS1-v1_5 is supported in this function. #### See Also VB6/C equivalent: [`RSA_EncodeMsg`](#RSA_EncodeMsg) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.EncodeMsgForEncryption Method Encode a message for encryption. #### Syntax [`C#`] ``` public static byte[] EncodeMsgForEncryption( int keyBytes, byte[] message, Rsa.EME method ) ``` [`VB.NET`] ``` Public Shared Function EncodeMsgForEncryption ( _ keyBytes As Integer, _ message As Byte(), _ method As Rsa.EME _ ) As Byte() ``` #### Parameters keyBytes : Number of bytes in the key message : Message to be encoded method : Type: [Rsa.EME](#T_Rsa_EME) Encoding method to use #### Return Value Encoded message block #### See Also VB6/C equivalent: [`RSA_EncodeMsg`](#RSA_EncodeMsg) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.EncodeMsgForSignature Method Encode a message for signature. #### Syntax [`C#`] ``` public static byte[] EncodeMsgForSignature( int keyBytes, byte[] message, HashAlgorithm hashAlg ) ``` [`VB.NET`] ``` Public Shared Function EncodeMsgForSignature ( _ keyBytes As Integer, _ message As Byte(), _ hashAlg As HashAlgorithm _ ) As Byte() ``` #### Parameters keyBytes : Number of bytes in the key message : Message to be encoded hashAlg : Type: [HashAlgorithm](#T_HashAlgorithm) Message digest algorithm to use #### Return Value Encoded block #### Remarks Only EMSA-PKCS1-v1_5 is supported in this function. Note we can only ever recover the *digest* from the encoded block. #### See Also VB6/C equivalent: [`RSA_EncodeMsg`](#RSA_EncodeMsg) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.EncodeMsgIso9796 Method Encode a message using ISO/IEC 9796-1 formatting. #### Syntax [`C#`] ``` public static byte[] EncodeMsgIso9796( byte[] message, int keyBits ) ``` [`VB.NET`] ``` Public Shared Function EncodeMsgIso9796 ( _ message As Byte(), _ keyBits As Integer _ ) As Byte() ``` #### Parameters message : message to be encoded keyBits : exact length of key in *bits* #### Return Value Padded message block ready for signing or an empty array on error #### Remarks The output block will be the same size as the key rounded up to the next whole byte. The message must be no longer than half the key length. #### See Also VB6/C equivalent: [`RSA_EncodeMsg`](#RSA_EncodeMsg) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.Encrypt Method Encrypt a short message using RSA encryption. #### Syntax [`C#`] ``` public static byte[] Encrypt( byte[] data, string publicKeyFile, Rsa.EME method, Rsa.HashAlg hashAlg, Rsa.AdvOptions advOpts ) ``` [`VB.NET`] ``` Public Shared Function Encrypt ( _ data As Byte(), _ publicKeyFile As String, _ method As Rsa.EME, _ hashAlg As Rsa.HashAlg, _ advOpts As Rsa.AdvOptions _ ) As Byte() ``` #### Parameters data : Data to be encrypted publicKeyFile : Name of the public key file or X.509 certificate, or a string containing the key or certificate in PEM format, or a valid internal public key string. method : Type: [Rsa.EME](#T_Rsa_EME) Encoding method [optional, default = EME.PKCSv1_5] hashAlg : Type: [Rsa.HashAlg](#T_Rsa_HashAlg) Hash function for EME-OAEP encoding, otherwise ignored. advOpts : Type: [Rsa.AdvOptions](#T_Rsa_AdvOptions) Advanced options for EME-OEAP only. #### Return Value Encrypted data or an empty array on error. #### See Also VB6/C equivalent: [`RSA_Encrypt`](#RSA_Encrypt) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.FromXMLString Method (String) Create an RSA key string in internal format from an XML string. #### Syntax [`C#`] ``` public static string FromXMLString( string xmlString ) ``` [`VB.NET`] ``` Public Shared Function FromXMLString ( _ xmlString As String _ ) As String ``` #### Parameters xmlString : The XML string to use to reconstruct the RSA key #### Return Value Key string in internal format or empty string on error #### Remarks Creates an internal private key string if the XML contains private key parameters, otherwise an internal public key string. #### See Also VB6/C equivalent: [`RSA_FromXMLString`](#RSA_FromXMLString) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.FromXMLString Method (String, Rsa.XmlOptions) Create an RSA key string in internal format from an XML string with options. #### Syntax [`C#`] ``` public static string FromXMLString( string xmlString, Rsa.XmlOptions options ) ``` [`VB.NET`] ``` Public Shared Function FromXMLString ( _ xmlString As String, _ options As Rsa.XmlOptions _ ) As String ``` #### Parameters xmlString : The XML string to use to reconstruct the RSA key options : Type: [Rsa.XmlOptions](#T_Rsa_XmlOptions) Option flags: set as zero for defaults. #### Return Value Key string in internal format or empty string on error #### See Also VB6/C equivalent: [`RSA_FromXMLString`](#RSA_FromXMLString) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.FromXMLString Method (String, Boolean) Create an RSA key string in internal format from an XML string with flag to exclude private key details. #### Syntax [`C#`] ``` public static string FromXMLString( string xmlString, bool excludePrivateParams ) ``` [`VB.NET`] ``` Public Shared Function FromXMLString ( _ xmlString As String, _ excludePrivateParams As Boolean _ ) As String ``` #### Parameters xmlString : The XML string to use to reconstruct the RSA key excludePrivateParams : Reconstruct public key details only #### Return Value Key string in internal format or empty string on error #### See Also VB6/C equivalent: [`RSA_FromXMLString`](#RSA_FromXMLString) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.GetPrivateKeyFromPFX Method Extract an encrypted private key from a PKCS-12 PKCS8ShroudedKeyBag, saving the output directly as a new file. #### Syntax [`C#`] ``` public static int GetPrivateKeyFromPFX( string outputFile, string pfxFile ) ``` [`VB.NET`] ``` Public Shared Function GetPrivateKeyFromPFX ( _ outputFile As String, _ pfxFile As String _ ) As Integer ``` #### Parameters outputFile : Name of new file to create pfxFile : PKCS-12 filename #### Return Value If successful, it returns the number of bytes written to the output file; otherwise it returns a negative [error code](#errorcodes) #### See Also VB6/C equivalent: [`RSA_GetPrivateKeyFromPFX`](#RSA_GetPrivateKeyFromPFX) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.GetPublicKeyFromCert Method Read public key from X.509 certificate into internal string format. #### Syntax [`C#`] ``` [ObsoleteAttribute("Use Rsa.ReadPublicKey() instead", false)] public static StringBuilder GetPublicKeyFromCert( string certFile ) ``` [`VB.NET`] ``` _ Public Shared Function GetPublicKeyFromCert ( _ certFile As String _ ) As StringBuilder ``` #### Parameters certFile : Filename of certificate file (or its base64 representation) #### Return Value StringBuilder containing an internal representation of the public key; or an empty StringBuilder if error #### Remarks This returns a StringBuilder, not a string. Use sb.ToString() to obtain a string. #### See Also VB6/C equivalent: [`RSA_GetPublicKeyFromCert`](#RSA_GetPublicKeyFromCert) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.KeyBits Method (String) Return number of significant bits in RSA key modulus. #### Syntax [`C#`] ``` public static int KeyBits( string strRsaKey ) ``` [`VB.NET`] ``` Public Shared Function KeyBits ( _ strRsaKey As String _ ) As Integer ``` #### Parameters strRsaKey : Internal key string #### Return Value Number of significant bits in key #### See Also VB6/C equivalent: [`RSA_KeyBits`](#RSA_KeyBits) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.KeyBits Method (StringBuilder) Return number of significant bits in RSA key modulus. #### Syntax [`C#`] ``` public static int KeyBits( StringBuilder sbRsaKey ) ``` [`VB.NET`] ``` Public Shared Function KeyBits ( _ sbRsaKey As StringBuilder _ ) As Integer ``` #### Parameters sbRsaKey : Internal key string #### Return Value Number of significant bits in key #### See Also VB6/C equivalent: [`RSA_KeyBits`](#RSA_KeyBits) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.KeyBytes Method (String) Return number of bytes (octets) in RSA key modulus. #### Syntax [`C#`] ``` public static int KeyBytes( string strRsaKey ) ``` [`VB.NET`] ``` Public Shared Function KeyBytes ( _ strRsaKey As String _ ) As Integer ``` #### Parameters strRsaKey : Internal key string #### Return Value Number of bytes in key #### See Also VB6/C equivalent: [`RSA_KeyBytes`](#RSA_KeyBytes) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.KeyBytes Method (StringBuilder) Return number of bytes (octets) in RSA key modulus. #### Syntax [`C#`] ``` public static int KeyBytes( StringBuilder sbRsaKey ) ``` [`VB.NET`] ``` Public Shared Function KeyBytes ( _ sbRsaKey As StringBuilder _ ) As Integer ``` #### Parameters sbRsaKey : Internal key string #### Return Value Number of bytes in key #### See Also VB6/C equivalent: [`RSA_KeyBytes`](#RSA_KeyBytes) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.KeyHashCode Method (String) Compute the hash code of an "internal" RSA public or private key string. #### Syntax [`C#`] ``` public static int KeyHashCode( string intKeyString ) ``` [`VB.NET`] ``` Public Shared Function KeyHashCode ( _ intKeyString As String _ ) As Integer ``` #### Parameters intKeyString : Internal key string #### Return Value A 32-bit hash code for the key, or zero on error. #### Remarks Should be the same for a matching private and public key. #### See Also VB6/C equivalent: [`RSA_KeyHashCode`](#RSA_KeyHashCode) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.KeyHashCode Method (StringBuilder) Compute the hash code of an "internal" RSA public or private key string. #### Syntax [`C#`] ``` public static int KeyHashCode( StringBuilder sbKeyString ) ``` [`VB.NET`] ``` Public Shared Function KeyHashCode ( _ sbKeyString As StringBuilder _ ) As Integer ``` #### Parameters sbKeyString : Internal key string #### Return Value A 32-bit hash code for the key, or zero on error. #### See Also VB6/C equivalent: [`RSA_KeyHashCode`](#RSA_KeyHashCode) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.KeyMatch Method (String, String) Verify that a pair of "internal" RSA private and public key strings are matched. #### Syntax [`C#`] ``` public static int KeyMatch( string privateKey, string publicKey ) ``` [`VB.NET`] ``` Public Shared Function KeyMatch ( _ privateKey As String, _ publicKey As String _ ) As Integer ``` #### Parameters privateKey : Internal RSA private key string publicKey : Internal RSA public key string #### Return Value 0=valid key pair, or negative [error code](#errorcodes) #### See Also VB6/C equivalent: [`RSA_KeyMatch`](#RSA_KeyMatch) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.KeyMatch Method (StringBuilder, StringBuilder) Verify that a pair of "internal" RSA private and public key strings are matched. #### Syntax [`C#`] ``` public static int KeyMatch( StringBuilder sbPrivateKey, StringBuilder sbPublicKey ) ``` [`VB.NET`] ``` Public Shared Function KeyMatch ( _ sbPrivateKey As StringBuilder, _ sbPublicKey As StringBuilder _ ) As Integer ``` #### Parameters sbPrivateKey : Internal RSA private key string sbPublicKey : Internal RSA public key string #### Return Value 0=valid key pair, or negative [error code](#errorcodes) #### See Also VB6/C equivalent: [`RSA_KeyMatch`](#RSA_KeyMatch) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.KeyValue Method Extract a base64-encoded RSA key value from internal key string #### Syntax [`C#`] ``` public static string KeyValue( string keyString, string fieldName ) ``` [`VB.NET`] ``` Public Shared Function KeyValue ( _ keyString As String, _ fieldName As String _ ) As String ``` #### Parameters keyString : Public or private key in internal string format fieldName : Name of field to be extracted: "Modulus" or "Exponent" #### Return Value Value encoded in base64 or an empty string on error #### Remarks The output is a continuous string of base64 characters suitable for a node in an XML-DSIG document. #### See Also VB6/C equivalent: [`RSA_KeyValue`](#RSA_KeyValue) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.MakeKeys Method (String, String, Int32, Rsa.PublicExponent, Int32, String, CipherAlgorithm, HashAlgorithm, Rsa.Format, Boolean) Generate an RSA public/private key pair with extended options for encrypting private key [DEPRECATED]. #### Syntax [`C#`] ``` [ObsoleteAttribute("Use Rsa.MakeKeys(String, String, String, Int32, Rsa.PublicExponent, Rsa.PbeOptions, String, Rsa.Format, Boolean) instead", false)] public static int MakeKeys( string publicKeyFile, string privateKeyFile, int bits, Rsa.PublicExponent exponent, int iterCount, string password, CipherAlgorithm cipherAlg, HashAlgorithm hashAlg, Rsa.Format fileFormat, bool showProgress ) ``` [`VB.NET`] ``` _ Public Shared Function MakeKeys ( _ publicKeyFile As String, _ privateKeyFile As String, _ bits As Integer, _ exponent As Rsa.PublicExponent, _ iterCount As Integer, _ password As String, _ cipherAlg As CipherAlgorithm, _ hashAlg As HashAlgorithm, _ fileFormat As Rsa.Format, _ showProgress As Boolean _ ) As Integer ``` #### Parameters publicKeyFile : Output filename for public key privateKeyFile : Output filename for (encrypted) private key bits : Required key modulus size in bits (min 96) exponent : Type: [Rsa.PublicExponent](#T_Rsa_PublicExponent) Exponent (Fermat Prime) iterCount : Iteration count for encrypted private key password : Password string for encrypted private key cipherAlg : Type: [CipherAlgorithm](#T_CipherAlgorithm) Block cipher to use for encryption scheme [default = des-ede3-cbc] hashAlg : Type: [HashAlgorithm](#T_HashAlgorithm) Hash function to use in PRF HMAC algorithm [default = hmacWithSHA1] fileFormat : Type: [Rsa.Format](#T_Rsa_Format) Format to save file [default = DER binary] showProgress : Indicate progress in console #### Return Value Zero if successful or non-zero [error code](#errorcodes) #### Remarks The private key is saved in encrypted PKCS#8 format using the PBES2 encryption scheme from PKCS#5 with key derivation function PBKDF2. #### See Also VB6/C equivalent: [`RSA_MakeKeys`](#RSA_MakeKeys) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.MakeKeys Method (String, String, Int32, Rsa.PublicExponent, Int32, String, Rsa.PbeOptions, Boolean, Byte[]) Generate an RSA public/private key pair [DEPRECATED]. #### Syntax [`C#`] ``` [ObsoleteAttribute("Use Rsa.MakeKeys(String, String, String, Int32, Rsa.PublicExponent, Rsa.PbeOptions, String, Rsa.Format, Boolean) instead", false)] public static int MakeKeys( string publicKeyFile, string privateKeyFile, int bits, Rsa.PublicExponent exponent, int iterCount, string password, Rsa.PbeOptions cryptOption, bool showProgress, byte[] seedBytes ) ``` [`VB.NET`] ``` _ Public Shared Function MakeKeys ( _ publicKeyFile As String, _ privateKeyFile As String, _ bits As Integer, _ exponent As Rsa.PublicExponent, _ iterCount As Integer, _ password As String, _ cryptOption As Rsa.PbeOptions, _ showProgress As Boolean, _ seedBytes As Byte() _ ) As Integer ``` #### Parameters publicKeyFile : Output filename for public key privateKeyFile : Output filename for (encrypted) private key bits : Required key modulus size in bits (min 96) exponent : Type: [Rsa.PublicExponent](#T_Rsa_PublicExponent) Exponent (Fermat Prime) iterCount : Iteration count for encrypted private key password : Password string for encrypted private key cryptOption : Type: [Rsa.PbeOptions](#T_Rsa_PbeOptions) Option to specify encryption algorithm for private key showProgress : Indicate progress in console seedBytes : (optional) User-supplied-entropy in byte format #### Return Value Zero if successful or non-zero [error code](#errorcodes) #### See Also VB6/C equivalent: [`RSA_MakeKeys`](#RSA_MakeKeys) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.MakeKeys Method (String, String, String, Int32, Rsa.PublicExponent, Rsa.PbeOptions, String, Rsa.Format, Boolean) Generate an RSA public/private key pair. #### Syntax [`C#`] ``` public static int MakeKeys( string publicKeyFile, string privateKeyFile, string password, int bits, Rsa.PublicExponent exponent, Rsa.PbeOptions pbes, string paramString, Rsa.Format fileFormat, bool showProgress ) ``` [`VB.NET`] ``` Public Shared Function MakeKeys ( _ publicKeyFile As String, _ privateKeyFile As String, _ password As String, _ bits As Integer, _ exponent As Rsa.PublicExponent, _ pbes As Rsa.PbeOptions, _ paramString As String, _ fileFormat As Rsa.Format, _ showProgress As Boolean _ ) As Integer ``` #### Parameters publicKeyFile : Output filename for public key privateKeyFile : Output filename for (encrypted) private key password : Password for encrypted private key bits : Required key modulus size in bits (min 96) exponent : Type: [Rsa.PublicExponent](#T_Rsa_PublicExponent) Exponent [default=65537=F4] pbes : Type: [Rsa.PbeOptions](#T_Rsa_PbeOptions) Encryption scheme to encrypt private key [default=pbeWithSHAAnd3-KeyTripleDES-CBC from PKCS#12] paramString : Optional parameters. A set of attribute name=value pairs separated by a semicolon ";" (see remarks) fileFormat : Type: [Rsa.Format](#T_Rsa_Format) Format to save file [default = DER binary] showProgress : Indicate progress in console #### Return Value Zero if successful or non-zero [error code](#errorcodes) #### Remarks Valid name-value pairs for paramString are: | **count**=integer | To set the iteration count used in the PBKDF2 method, e.g. "count=5000;" [default=2048]. | | --- | --- | | **prf**=hmac-name | To change the HMAC algorithm used in the PBKDF2 method, e.g. "prf=hmacwithSHA256;" [default=hmacwithSHA1]. | Valid values for hmac-name are {hmacWithSHA1|hmacWithSHA224|hmacWithSHA256|hmacWithSHA384|hmacWithSHA512}. #### See Also VB6/C equivalent: [`RSA_MakeKeysXtd`](#RSA_MakeKeysXtd) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.PublicKeyFromPrivate Method Convert an internal private key string into a public one. #### Syntax [`C#`] ``` public static StringBuilder PublicKeyFromPrivate( StringBuilder sbKeyString ) ``` [`VB.NET`] ``` Public Shared Function PublicKeyFromPrivate ( _ sbKeyString As StringBuilder _ ) As StringBuilder ``` #### Parameters sbKeyString : StringBuilder containing private key in "internal" format #### Return Value StringBuilder containing an internal representation of the public key; or an empty StringBuilder if error #### Remarks This returns a StringBuilder, not a string. Use sb.ToString() to obtain a string. #### See Also VB6/C equivalent: [`RSA_PublicKeyFromPrivate`](#RSA_PublicKeyFromPrivate) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.RawPrivate Method (Byte[], String) Carry out RSA transformation using private key. #### Syntax [`C#`] ``` public static byte[] RawPrivate( byte[] data, string privateKeyStr ) ``` [`VB.NET`] ``` Public Shared Function RawPrivate ( _ data As Byte(), _ privateKeyStr As String _ ) As Byte() ``` #### Parameters data : Data (**must** be same byte length as key modulus) privateKeyStr : Private key in internal string format #### Return Value Transformed data #### See Also VB6/C equivalent: [`RSA_RawPrivate`](#RSA_RawPrivate) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.RawPrivate Method (Byte[], String, Int32) Carry out RSA transformation using private key (with specialist options). #### Syntax [`C#`] ``` public static byte[] RawPrivate( byte[] data, string privateKeyStr, int options ) ``` [`VB.NET`] ``` Public Shared Function RawPrivate ( _ data As Byte(), _ privateKeyStr As String, _ options As Integer _ ) As Byte() ``` #### Parameters data : Data (**must** be same byte length as key modulus) privateKeyStr : Private key in internal string format options : Specialist options value #### Return Value Transformed data #### See Also VB6/C equivalent: [`RSA_RawPrivate`](#RSA_RawPrivate) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.RawPublic Method (Byte[], String) Carry out RSA transformation using public key. #### Syntax [`C#`] ``` public static byte[] RawPublic( byte[] data, string publicKeyStr ) ``` [`VB.NET`] ``` Public Shared Function RawPublic ( _ data As Byte(), _ publicKeyStr As String _ ) As Byte() ``` #### Parameters data : Data (**must** be same byte length as key modulus) publicKeyStr : Public key in internal string format #### Return Value Transformed data #### See Also VB6/C equivalent: [`RSA_RawPublic`](#RSA_RawPublic) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.RawPublic Method (Byte[], String, Int32) Carry out RSA transformation using public key (with specialist options). #### Syntax [`C#`] ``` public static byte[] RawPublic( byte[] data, string publicKeyStr, int options ) ``` [`VB.NET`] ``` Public Shared Function RawPublic ( _ data As Byte(), _ publicKeyStr As String, _ options As Integer _ ) As Byte() ``` #### Parameters data : Data (**must** be same byte length as key modulus) publicKeyStr : Public key in internal string format options : Specialist options value #### Return Value Transformed data #### See Also VB6/C equivalent: [`RSA_RawPublic`](#RSA_RawPublic) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.ReadEncPrivateKey Method Read encrypted private key file into internal string format. #### Syntax [`C#`] ``` [ObsoleteAttribute("Use Rsa.ReadPrivateKey() instead", false)] public static StringBuilder ReadEncPrivateKey( string privateKeyFile, string password ) ``` [`VB.NET`] ``` _ Public Shared Function ReadEncPrivateKey ( _ privateKeyFile As String, _ password As String _ ) As StringBuilder ``` #### Parameters privateKeyFile : filename of a binary BER-encoded encrypted private key info file password : password for key file #### Return Value StringBuilder containing an internal representation of the private key; or an empty StringBuilder if error #### Remarks This returns a StringBuilder, not a string. Use sb.ToString() to obtain a string. #### See Also VB6/C equivalent: [`RSA_ReadEncPrivateKey`](#RSA_ReadEncPrivateKey) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.ReadPrivateKey Method Read from a file or string containing a private key into an "internal" private key string. #### Syntax [`C#`] ``` public static StringBuilder ReadPrivateKey( string privateKeyFile, string password ) ``` [`VB.NET`] ``` Public Shared Function ReadPrivateKey ( _ privateKeyFile As String, _ password As String _ ) As StringBuilder ``` #### Parameters privateKeyFile : Name of private key file or a PEM String containing the key password : Password for private key, if encrypted #### Return Value StringBuilder containing an internal representation of the private key; or an empty StringBuilder if error #### Remarks This returns a StringBuilder, not a string, to allow secure wiping. Use sb.ToString() to obtain a string. #### See Also VB6/C equivalent: [`RSA_ReadAnyPrivateKey`](#RSA_ReadAnyPrivateKey) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.ReadPrivateKeyFromPFX Method Read a private key directly from an encrypted PFX/PKCS-12 file into an "internal" private key string. #### Syntax [`C#`] ``` [ObsoleteAttribute("Use Rsa.ReadPrivateKey() instead", false)] public static StringBuilder ReadPrivateKeyFromPFX( string pfxFile, string password ) ``` [`VB.NET`] ``` _ Public Shared Function ReadPrivateKeyFromPFX ( _ pfxFile As String, _ password As String _ ) As StringBuilder ``` #### Parameters pfxFile : PKCS-12 filename password : Password for PFX file #### Return Value StringBuilder containing an internal representation of the private key; or an empty StringBuilder if error #### Remarks This returns a StringBuilder, not a string. Use sb.ToString() to obtain a string. #### See Also VB6/C equivalent: [`RSA_ReadPrivateKeyFromPFX`](#RSA_ReadPrivateKeyFromPFX) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.ReadPrivateKeyInfo Method Read from an (unencrypted) PKCS-8 private key info file into a private key string. #### Syntax [`C#`] ``` [ObsoleteAttribute("Use Rsa.ReadPrivateKey() instead", false)] public static StringBuilder ReadPrivateKeyInfo( string prikeyinfoFile ) ``` [`VB.NET`] ``` _ Public Shared Function ReadPrivateKeyInfo ( _ prikeyinfoFile As String _ ) As StringBuilder ``` #### Parameters prikeyinfoFile : Name of file #### Return Value StringBuilder containing an internal representation of the private key; or an empty StringBuilder if error #### Remarks This returns a StringBuilder, not a string. Use sb.ToString() to obtain a string. #### See Also VB6/C equivalent: [`RSA_ReadPrivateKeyInfo`](#RSA_ReadPrivateKeyInfo) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.ReadPublicKey Method Read from a file or string containing a public key into an "internal" public key string. #### Syntax [`C#`] ``` public static StringBuilder ReadPublicKey( string certOrPublicKeyFile ) ``` [`VB.NET`] ``` Public Shared Function ReadPublicKey ( _ certOrPublicKeyFile As String _ ) As StringBuilder ``` #### Parameters certOrPublicKeyFile : Name of X.509 certificate or public key file or a PEM String containing the key #### Return Value StringBuilder containing an internal representation of the public key; or an empty StringBuilder if error #### Remarks This returns a StringBuilder, not a string. Use sb.ToString() to obtain a string. #### See Also VB6/C equivalent: [`RSA_ReadPublicKey`](#RSA_ReadPublicKey) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.SaveEncKey Method Save an internal RSA key string to an encrypted key file. #### Syntax [`C#`] ``` public static int SaveEncKey( string outputFile, string privateKey, string password, Rsa.PbeOptions pbeOption, string paramString, Rsa.Format format ) ``` [`VB.NET`] ``` Public Shared Function SaveEncKey ( _ outputFile As String, _ privateKey As String, _ password As String, _ pbeOption As Rsa.PbeOptions, _ paramString As String, _ format As Rsa.Format _ ) As Integer ``` #### Parameters outputFile : Name of output file to be created privateKey : The private RSA key as an internal key string. password : Password to be used for the encrypted key file. pbeOption : Type: [Rsa.PbeOptions](#T_Rsa_PbeOptions) Encryption scheme to encrypt private key [default = pbeWithSHAAnd3-KeyTripleDES-CBC from PKCS#12] paramString : Optional parameters. A set of attribute name=value pairs separated by a semicolon ";" (see remarks). format : Type: [Rsa.Format](#T_Rsa_Format) File format #### Return Value If successful, the return value is zero; otherwise it returns a nonzero [error code](#errorcodes) #### Remarks Valid name-value pairs for paramString are: | **count**=integer | To set the iteration count used in the PBKDF2 method, e.g. "count=5000;" [default=2048]. | | --- | --- | | **prf**=hmac-name | To change the HMAC algorithm used in the PBKDF2 method, e.g. "prf=hmacwithSHA256;" [default=hmacwithSHA1]. | Valid values for hmac-name are {hmacWithSHA1|hmacWithSHA224|hmacWithSHA256|hmacWithSHA384|hmacWithSHA512}. #### See Also VB6/C equivalent: [`RSA_SaveEncKey`](#RSA_SaveEncKey) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.SaveEncPrivateKey Method (String, String, Int32, String, CipherAlgorithm, HashAlgorithm, Rsa.Format) Save a private key string to a PKCS-8 EncryptedPrivateKeyInfo file using PBES2 algorithm [DEPRECATED]. #### Syntax [`C#`] ``` public static int SaveEncPrivateKey( string outputFile, string privateKey, int iterationCount, string password, CipherAlgorithm cipherAlg, HashAlgorithm hashAlg, Rsa.Format format ) ``` [`VB.NET`] ``` Public Shared Function SaveEncPrivateKey ( _ outputFile As String, _ privateKey As String, _ iterationCount As Integer, _ password As String, _ cipherAlg As CipherAlgorithm, _ hashAlg As HashAlgorithm, _ format As Rsa.Format _ ) As Integer ``` #### Parameters outputFile : Name of file to create privateKey : Private key in internal format iterationCount : Iteration count to be used when encrypting file password : Password string cipherAlg : Type: [CipherAlgorithm](#T_CipherAlgorithm) Block cipher to use for encryption scheme [default = des-ede3-cbc] hashAlg : Type: [HashAlgorithm](#T_HashAlgorithm) Hash function to use in PRF HMAC algorithm [default = hmacWithSHA1] format : Type: [Rsa.Format](#T_Rsa_Format) File format #### Return Value If successful, the return value is zero; otherwise it returns a nonzero [error code](#errorcodes) #### See Also VB6/C equivalent: [`RSA_SaveEncPrivateKey`](#RSA_SaveEncPrivateKey) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.SaveEncPrivateKey Method (String, String, Int32, String, Rsa.PbeOptions, Rsa.Format) Save a private key string to a PKCS-8 EncryptedPrivateKeyInfo file [DEPRECATED]. #### Syntax [`C#`] ``` public static int SaveEncPrivateKey( string outputFile, string privateKey, int iterationCount, string password, Rsa.PbeOptions pbeOption, Rsa.Format format ) ``` [`VB.NET`] ``` Public Shared Function SaveEncPrivateKey ( _ outputFile As String, _ privateKey As String, _ iterationCount As Integer, _ password As String, _ pbeOption As Rsa.PbeOptions, _ format As Rsa.Format _ ) As Integer ``` #### Parameters outputFile : Name of file to create privateKey : Private key in internal format iterationCount : Iteration count to be used when encrypting file password : Password string pbeOption : Type: [Rsa.PbeOptions](#T_Rsa_PbeOptions) Type of password-based encryption to use [default = pbeWithSHAAnd3-KeyTripleDES-CBC] format : Type: [Rsa.Format](#T_Rsa_Format) File format #### Return Value If successful, the return value is zero; otherwise it returns a nonzero [error code](#errorcodes) #### See Also VB6/C equivalent: [`RSA_SaveEncPrivateKey`](#RSA_SaveEncPrivateKey) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.SavePrivateKeyInfo Method Save a private key string to an (unencrypted) PKCS-8 private key info file. #### Syntax [`C#`] ``` public static int SavePrivateKeyInfo( string outputFile, string privateKey, Rsa.Format format ) ``` [`VB.NET`] ``` Public Shared Function SavePrivateKeyInfo ( _ outputFile As String, _ privateKey As String, _ format As Rsa.Format _ ) As Integer ``` #### Parameters outputFile : Name of file to create privateKey : Private key in internal format format : Type: [Rsa.Format](#T_Rsa_Format) File format #### Return Value If successful, the return value is zero; otherwise it returns a nonzero [error code](#errorcodes) #### Remarks Do **not** use for a production key. #### See Also VB6/C equivalent: [`RSA_SavePrivateKeyInfo`](#RSA_SavePrivateKeyInfo) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.SavePublicKey Method Save a public key string to PKCS-1 public key file. #### Syntax [`C#`] ``` public static int SavePublicKey( string outputFile, string publicKey, Rsa.Format format ) ``` [`VB.NET`] ``` Public Shared Function SavePublicKey ( _ outputFile As String, _ publicKey As String, _ format As Rsa.Format _ ) As Integer ``` #### Parameters outputFile : Name of file to create publicKey : Public key in internal format format : Type: [Rsa.Format](#T_Rsa_Format) File format #### Return Value If successful, the return value is zero; otherwise it returns a nonzero [error code](#errorcodes) #### See Also VB6/C equivalent: [`RSA_SavePublicKey`](#RSA_SavePublicKey) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.ToXMLString Method (String, Rsa.XmlOptions) Create an XML string representation of an RSA internal key string. #### Syntax [`C#`] ``` public static string ToXMLString( string intKeyString, Rsa.XmlOptions options ) ``` [`VB.NET`] ``` Public Shared Function ToXMLString ( _ intKeyString As String, _ options As Rsa.XmlOptions _ ) As String ``` #### Parameters intKeyString : Internal key string options : Type: [Rsa.XmlOptions](#T_Rsa_XmlOptions) Option flags: set as zero for defaults. #### Return Value XML string or empty string on error #### See Also VB6/C equivalent: [`RSA_ToXMLString`](#RSA_ToXMLString) [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.ToXMLString Method (String, String, Rsa.XmlOptions) Create an XML string representation of an RSA internal key string with option to add a namespace prefix. #### Syntax [`C#`] ``` public static string ToXMLString( string intKeyString, string prefix, Rsa.XmlOptions options ) ``` [`VB.NET`] ``` Public Shared Function ToXMLString ( _ intKeyString As String, _ prefix As String, _ options As Rsa.XmlOptions _ ) As String ``` #### Parameters intKeyString : Internal key string prefix : Prefix to add to elements, e.g. "ds" or "ds:". options : Type: [Rsa.XmlOptions](#T_Rsa_XmlOptions) Option flags: set as zero for defaults. #### Return Value XML string or empty string on error #### Remarks Use this extended function to add a namespace prefix to all elements in the XML output; for example, . Note that it's up to the user to map the prefix to a URI somewhere in the final XML document. #### See Also VB6/C equivalent: [`RSA_ToXMLStringEx`](#RSA_ToXMLStringEx) [[Contents](#topofpage)] [[Index](#index)] --- ### Sig.GetHashAlgFromSigAlg Method Get the hash algorithm used in the signature algorithm. #### Syntax [`C#`] ``` public static HashAlgorithm GetHashAlgFromSigAlg( SigAlgorithm sigAlg ) ``` [`VB.NET`] ``` Public Shared Function GetHashAlgFromSigAlg ( _ sigAlg As SigAlgorithm _ ) As HashAlgorithm ``` #### Parameters sigAlg : Type: [SigAlgorithm](#T_SigAlgorithm) Signature algorithm #### Return Value Hash algorithm used in sigAlg [[Contents](#topofpage)] [[Index](#index)] --- ### Sig.SignData Method Compute a signature value over data in a byte array. #### Syntax [`C#`] ``` public static string SignData( byte[] data, string privateKeyFile, string password, SigAlgorithm sigAlg, Sig.SigOptions sigOpts, Sig.Encoding sigEncoding ) ``` [`VB.NET`] ``` Public Shared Function SignData ( _ data As Byte(), _ privateKeyFile As String, _ password As String, _ sigAlg As SigAlgorithm, _ sigOpts As Sig.SigOptions, _ sigEncoding As Sig.Encoding _ ) As String ``` #### Parameters data : input data to be signed privateKeyFile : Name of private key file (or a string containing the key in PEM format, or an internal private key) password : Password for the private key, if encrypted sigAlg : Type: [SigAlgorithm](#T_SigAlgorithm) Signature algorithm to be used sigOpts : Type: [Sig.SigOptions](#T_Sig_SigOptions) (optional) Options for ECDSA and RSA-PSS signatures sigEncoding : Type: [Sig.Encoding](#T_Sig_Encoding) Optional encodings for output [default=base64] #### Return Value The encoded signature, or an empty string on error #### See Also VB6/C equivalent: [`SIG_SignData`](#SIG_SignData) [[Contents](#topofpage)] [[Index](#index)] --- ### Sig.SignDigest Method Compute a signature value over a message digest value. #### Syntax [`C#`] ``` public static string SignDigest( byte[] digest, string privateKeyFile, string password, SigAlgorithm sigAlg, Sig.SigOptions sigOpts, Sig.Encoding sigEncoding ) ``` [`VB.NET`] ``` Public Shared Function SignDigest ( _ digest As Byte(), _ privateKeyFile As String, _ password As String, _ sigAlg As SigAlgorithm, _ sigOpts As Sig.SigOptions, _ sigEncoding As Sig.Encoding _ ) As String ``` #### Parameters digest : digest value in a byte array privateKeyFile : Name of private key file (or a string containing the key in PEM format, or an internal private key) password : Password for the private key, if encrypted sigAlg : Type: [SigAlgorithm](#T_SigAlgorithm) Signature algorithm to be used sigOpts : Type: [Sig.SigOptions](#T_Sig_SigOptions) (optional) Options for ECDSA and RSA-PSS signatures sigEncoding : Type: [Sig.Encoding](#T_Sig_Encoding) Optional encodings for output [default=base64] #### Return Value The encoded signature, or an empty string on error #### See Also VB6/C equivalent: [`SIG_SignData`](#SIG_SignData) [[Contents](#topofpage)] [[Index](#index)] --- ### Sig.SignFile Method Compute a signature value over binary data in a file. #### Syntax [`C#`] ``` public static string SignFile( string dataFile, string privateKeyFile, string password, SigAlgorithm sigAlg, Sig.SigOptions sigOpts, Sig.Encoding sigEncoding ) ``` [`VB.NET`] ``` Public Shared Function SignFile ( _ dataFile As String, _ privateKeyFile As String, _ password As String, _ sigAlg As SigAlgorithm, _ sigOpts As Sig.SigOptions, _ sigEncoding As Sig.Encoding _ ) As String ``` #### Parameters dataFile : Name of input file containing data to be signed privateKeyFile : Name of private key file (or a string containing the key in PEM format, or an internal private key) password : Password for the private key, if encrypted sigAlg : Type: [SigAlgorithm](#T_SigAlgorithm) Signature algorithm to be used sigOpts : Type: [Sig.SigOptions](#T_Sig_SigOptions) (optional) Options for ECDSA and RSA-PSS signatures sigEncoding : Type: [Sig.Encoding](#T_Sig_Encoding) Optional encodings for output [default=base64] #### Return Value The encoded signature, or an empty string on error #### See Also VB6/C equivalent: [`SIG_SignFile`](#SIG_SignFile) [[Contents](#topofpage)] [[Index](#index)] --- ### Sig.VerifyData Method Verify a signature value over data in a byte array. #### Syntax [`C#`] ``` public static int VerifyData( string sigStr, byte[] data, string certOrKeyFile, SigAlgorithm sigAlg, Sig.VerifyOpts opts ) ``` [`VB.NET`] ``` Public Shared Function VerifyData ( _ sigStr As String, _ data As Byte(), _ certOrKeyFile As String, _ sigAlg As SigAlgorithm, _ opts As Sig.VerifyOpts _ ) As Integer ``` #### Parameters sigStr : Encoded signature value data : Input data to be verified certOrKeyFile : The X.509 certificate or public key file name (or a string containing the certificate or key in PEM format or base64 representation, or an internal key string). sigAlg : Type: [SigAlgorithm](#T_SigAlgorithm) Signature algorithm used to create signature. opts : Type: [Sig.VerifyOpts](#T_Sig_VerifyOpts) (optional) Advanced options for RSA-PSS only. #### Return Value Zero (0) if the signature is valid; otherwise a negative [error code](#errorcodes). #### Remarks Any valid encodings of the signature value are detected automatically. #### See Also VB6/C equivalent: [`SIG_VerifyData`](#SIG_VerifyData) [[Contents](#topofpage)] [[Index](#index)] --- ### Sig.VerifyDigest Method Verify a signature value over a message digest value of data. #### Syntax [`C#`] ``` public static int VerifyDigest( string sigStr, byte[] digest, string certOrKeyFile, SigAlgorithm sigAlg, Sig.VerifyOpts opts ) ``` [`VB.NET`] ``` Public Shared Function VerifyDigest ( _ sigStr As String, _ digest As Byte(), _ certOrKeyFile As String, _ sigAlg As SigAlgorithm, _ opts As Sig.VerifyOpts _ ) As Integer ``` #### Parameters sigStr : Containing the encoded signature value digest : Byte array containing the message digest value of the data to be verified certOrKeyFile : Specifying the X.509 certificate or public key file name (or a string containing the certificate or key in PEM format or base64 representation, or an internal key string). sigAlg : Type: [SigAlgorithm](#T_SigAlgorithm) Signature algorithm used to create signature. opts : Type: [Sig.VerifyOpts](#T_Sig_VerifyOpts) Advanced options for RSA-PSS only (optional) #### Return Value Zero (0) if the signature is valid; otherwise a negative [error code](#errorcodes). #### Remarks Any valid encodings of the signature value are detected automatically. #### See Also VB6/C equivalent: [`SIG_VerifyData`](#SIG_VerifyData) [[Contents](#topofpage)] [[Index](#index)] --- ### Sig.VerifyFile Method Verify a signature value over data in a file. #### Syntax [`C#`] ``` public static int VerifyFile( string sigStr, string dataFile, string certOrKeyFile, SigAlgorithm sigAlg, Sig.VerifyOpts opts ) ``` [`VB.NET`] ``` Public Shared Function VerifyFile ( _ sigStr As String, _ dataFile As String, _ certOrKeyFile As String, _ sigAlg As SigAlgorithm, _ opts As Sig.VerifyOpts _ ) As Integer ``` #### Parameters sigStr : Containing the encoded signature value dataFile : Name of file containing data to be verified certOrKeyFile : Specifying the X.509 certificate or public key file name (or a string containing the certificate or key in PEM format or base64 representation, or an internal key string). sigAlg : Type: [SigAlgorithm](#T_SigAlgorithm) Signature algorithm used to create signature. opts : Type: [Sig.VerifyOpts](#T_Sig_VerifyOpts) Advanced options for RSA-PSS only (optional) #### Return Value Zero (0) if the signature is valid; otherwise a negative [error code](#errorcodes). #### Remarks Any valid encodings of the signature value are detected automatically. #### See Also VB6/C equivalent: [`SIG_VerifyFile`](#SIG_VerifyFile) [[Contents](#topofpage)] [[Index](#index)] --- ### Smime.Extract Method Extract the body from an S/MIME entity. #### Syntax [`C#`] ``` public static int Extract( string outputFile, string inputFile, Smime.Options opts ) ``` [`VB.NET`] ``` Public Shared Function Extract ( _ outputFile As String, _ inputFile As String, _ opts As Smime.Options _ ) As Integer ``` #### Parameters outputFile : Name of output file to be created inputFile : Name of input file containing S/MIME entity opts : Type: [Smime.Options](#T_Smime_Options) Options #### Return Value A positive number giving the size of the output file in bytes; otherwise it returns an [error code](#errorcodes) #### Remarks This is designed to extract the body from an S/MIME entity with a content type of application/pkcs7-mime with base64 or binary transfer encoding. In practice, it will extract the body from almost any type of S/MIME (or MIME) file, except one with quoted-printable transfer encoding. By default the output is encoded in binary. Use the EncodeBase64 option to encode the output in base64. #### See Also VB6/C equivalent: [`SMIME_Extract`](#SMIME_Extract) [[Contents](#topofpage)] [[Index](#index)] --- ### Smime.Query Method Query an S/MIME entity for selected information. #### Syntax [`C#`] ``` public static string Query( string inputFile, string query ) ``` [`VB.NET`] ``` Public Shared Function Query ( _ inputFile As String, _ query As String _ ) As String ``` #### Parameters inputFile : Name of file containing S/MIME entity query : Query string (case insensitive) #### Return Value String containing the result or an empty string if not found or error. #### Remarks Valid queries are: | "content-type" | Value of Content-Type, e.g. "application/pkcs7-mime". | | --- | --- | | "smime-type" | Value of smime-type parameter of Content-Type, e.g. , e.g. "enveloped-data". | | "encoding" | Value of Content-Transfer-Encoding, e.g. "base64". | | "name" | Value of name parameter of Content-Type, e.g. "smime.p7m" | | "filename" | Value of filename parameter of Content-Disposition, e.g. "smime.p7m". | #### See Also VB6/C equivalent: [`SMIME_Query`](#SMIME_Query) [[Contents](#topofpage)] [[Index](#index)] --- ### Smime.Wrap Method Wrap a CMS object in an S/MIME entity. #### Syntax [`C#`] ``` public static int Wrap( string outputFile, string inputFile, Smime.Options opts ) ``` [`VB.NET`] ``` Public Shared Function Wrap ( _ outputFile As String, _ inputFile As String, _ opts As Smime.Options _ ) As Integer ``` #### Parameters outputFile : Output file to be created inputFile : Input file containing CMS object opts : Type: [Smime.Options](#T_Smime_Options) Options #### Return Value A positive number giving the size of the output file in bytes; otherwise it returns an [error code](#errorcodes) #### Remarks The input file is expected to be a binary CMS object of type enveloped-data, signed-data or compressed-data; otherwise it is an error. The type of input file is detected automatically. By default the body is encoded in base64 encoding. Use the EncodeBinary option to encode the body in binary. #### See Also VB6/C equivalent: [`SMIME_Wrap`](#SMIME_Wrap) [[Contents](#topofpage)] [[Index](#index)] --- ### Tdea.Decrypt Method (Byte[], Byte[], Mode, Byte[]) Decrypt data in byte array. #### Syntax [`C#`] ``` public static byte[] Decrypt( byte[] input, byte[] key, Mode mode, byte[] iv ) ``` [`VB.NET`] ``` Public Shared Function Decrypt ( _ input As Byte(), _ key As Byte(), _ mode As Mode, _ iv As Byte() _ ) As Byte() ``` #### Parameters input : Input data key : Key of exactly 24 bytes (192 bits) mode : Type: [Mode](#T_Mode) Cipher Mode iv : IV of exactly 8 bytes or null for ECB mode #### Return Value Decrypted data in byte array or empty array on error #### Remarks For ECB and CBC modes, input data length **must** be an exact multiple of the block length #### See Also VB6/C equivalent: [`TDEA_BytesMode`](#TDEA_BytesMode) [[Contents](#topofpage)] [[Index](#index)] --- ### Tdea.Decrypt Method (String, String, Mode, String) Decrypt hex-encoded data string. #### Syntax [`C#`] ``` public static string Decrypt( string inputHex, string keyHex, Mode mode, string ivHex ) ``` [`VB.NET`] ``` Public Shared Function Decrypt ( _ inputHex As String, _ keyHex As String, _ mode As Mode, _ ivHex As String _ ) As String ``` #### Parameters inputHex : Hex-encoded input data keyHex : Hex-encoded key representing exactly 24 bytes (192 bits) mode : Type: [Mode](#T_Mode) Cipher Mode ivHex : Hex-encoded IV representing exactly 8 bytes or "" for ECB mode #### Return Value Decrypted data in hex-encoded string or empty string on error #### Remarks For ECB and CBC modes, the length of the decoded input bytes **must** be an exact multiple of the block length #### See Also VB6/C equivalent: [`TDEA_HexMode`](#TDEA_HexMode) [[Contents](#topofpage)] [[Index](#index)] --- ### Tdea.Decrypt Method (String, String, Mode, String, EncodingBase) Decrypt encoded data string. #### Syntax [`C#`] ``` public static string Decrypt( string inputStr, string keyStr, Mode mode, string ivStr, EncodingBase encodingBase ) ``` [`VB.NET`] ``` Public Shared Function Decrypt ( _ inputStr As String, _ keyStr As String, _ mode As Mode, _ ivStr As String, _ encodingBase As EncodingBase _ ) As String ``` #### Parameters inputStr : Encoded input data keyStr : Encoded key representing exactly 24 bytes (192 bits) mode : Type: [Mode](#T_Mode) Cipher Mode ivStr : Encoded IV representing exactly 8 bytes or "" for ECB mode encodingBase : Type: [EncodingBase](#T_EncodingBase) Type of encoding used #### Return Value Decrypted data in encoded string or empty string on error #### Remarks For ECB and CBC modes, the length of the decoded input bytes **must** be an exact multiple of the block length #### See Also VB6/C equivalent: [`TDEA_B64Mode`](#TDEA_B64Mode) [[Contents](#topofpage)] [[Index](#index)] --- ### Tdea.Encrypt Method (Byte[], Byte[], Mode, Byte[]) Encrypt data in byte array. #### Syntax [`C#`] ``` public static byte[] Encrypt( byte[] input, byte[] key, Mode mode, byte[] iv ) ``` [`VB.NET`] ``` Public Shared Function Encrypt ( _ input As Byte(), _ key As Byte(), _ mode As Mode, _ iv As Byte() _ ) As Byte() ``` #### Parameters input : Input data key : Key of exactly 24 bytes (192 bits) mode : Type: [Mode](#T_Mode) Cipher Mode iv : IV of exactly 8 bytes or null for ECB mode #### Return Value Ciphertext in byte array or empty array on error #### Remarks For ECB and CBC modes, input data length **must** be an exact multiple of the block length #### See Also VB6/C equivalent: [`TDEA_BytesMode`](#TDEA_BytesMode) [[Contents](#topofpage)] [[Index](#index)] --- ### Tdea.Encrypt Method (String, String, Mode, String) Encrypt hex-encoded data string. #### Syntax [`C#`] ``` public static string Encrypt( string inputHex, string keyHex, Mode mode, string ivHex ) ``` [`VB.NET`] ``` Public Shared Function Encrypt ( _ inputHex As String, _ keyHex As String, _ mode As Mode, _ ivHex As String _ ) As String ``` #### Parameters inputHex : Hex-encoded input data keyHex : Hex-encoded key representing exactly 24 bytes (192 bits) mode : Type: [Mode](#T_Mode) Cipher Mode ivHex : Hex-encoded IV representing exactly 8 bytes or "" for ECB mode #### Return Value Ciphertext in hex-encoded string or empty string on error #### Remarks For ECB and CBC modes, the length of the decoded input bytes **must** be an exact multiple of the block length #### See Also VB6/C equivalent: [`TDEA_HexMode`](#TDEA_HexMode) [[Contents](#topofpage)] [[Index](#index)] --- ### Tdea.Encrypt Method (String, String, Mode, String, EncodingBase) Encrypt encoded data string. #### Syntax [`C#`] ``` public static string Encrypt( string inputStr, string keyStr, Mode mode, string ivStr, EncodingBase encodingBase ) ``` [`VB.NET`] ``` Public Shared Function Encrypt ( _ inputStr As String, _ keyStr As String, _ mode As Mode, _ ivStr As String, _ encodingBase As EncodingBase _ ) As String ``` #### Parameters inputStr : Encoded input data keyStr : Encoded key representing exactly 24 bytes (192 bits) mode : Type: [Mode](#T_Mode) Cipher Mode ivStr : Encoded IV representing exactly 8 bytes or "" for ECB mode encodingBase : Type: [EncodingBase](#T_EncodingBase) Type of encoding used #### Return Value Ciphertext in hex-encoded string or empty string on error #### Remarks For ECB and CBC modes, the length of the decoded input bytes **must** be an exact multiple of the block length #### See Also VB6/C equivalent: [`TDEA_B64Mode`](#TDEA_B64Mode) [[Contents](#topofpage)] [[Index](#index)] --- ### Tdea.FileDecrypt Method (String, String, Byte[], Mode, Byte[]) Decrypt a file. #### Syntax [`C#`] ``` public static int FileDecrypt( string fileOut, string fileIn, byte[] key, Mode mode, byte[] iv ) ``` [`VB.NET`] ``` Public Shared Function FileDecrypt ( _ fileOut As String, _ fileIn As String, _ key As Byte(), _ mode As Mode, _ iv As Byte() _ ) As Integer ``` #### Parameters fileOut : Name of output file to be created or overwritten fileIn : Name of input file key : Key of exactly 8 bytes (64 bits) mode : Type: [Mode](#T_Mode) Cipher Mode iv : IV of exactly 8 bytes or null for ECB mode #### Return Value 0 if successful or non-zero [error code](#errorcodes) #### Remarks fileOut and fileIn must **not** be the same #### See Also VB6/C equivalent: [`TDEA_File`](#TDEA_File) [[Contents](#topofpage)] [[Index](#index)] --- ### Tdea.FileDecrypt Method (String, String, String, Mode, String) Decrypt a file passing key and IV as hex strings. #### Syntax [`C#`] ``` public static int FileDecrypt( string fileOut, string fileIn, string keyHex, Mode mode, string ivHex ) ``` [`VB.NET`] ``` Public Shared Function FileDecrypt ( _ fileOut As String, _ fileIn As String, _ keyHex As String, _ mode As Mode, _ ivHex As String _ ) As Integer ``` #### Parameters fileOut : Name of output file to be created or overwritten fileIn : Name of input file keyHex : Hex-encoded key of exact length mode : Type: [Mode](#T_Mode) Cipher Mode ivHex : Hex-encoded IV or "" for ECB mode #### Return Value 0 if successful or non-zero [error code](#errorcodes) #### Remarks fileOut and fileIn must **not** be the same. The output file is in binary format. [[Contents](#topofpage)] [[Index](#index)] --- ### Tdea.FileEncrypt Method (String, String, Byte[], Mode, Byte[]) Encrypt a file. #### Syntax [`C#`] ``` public static int FileEncrypt( string fileOut, string fileIn, byte[] key, Mode mode, byte[] iv ) ``` [`VB.NET`] ``` Public Shared Function FileEncrypt ( _ fileOut As String, _ fileIn As String, _ key As Byte(), _ mode As Mode, _ iv As Byte() _ ) As Integer ``` #### Parameters fileOut : Name of output file to be created or overwritten fileIn : Name of input file key : Key of exactly 24 bytes (192 bits) mode : Type: [Mode](#T_Mode) Cipher Mode iv : IV of exactly 8 bytes or null for ECB mode #### Return Value 0 if successful or non-zero [error code](#errorcodes) #### Remarks fileOut and fileIn must **not** be the same #### See Also VB6/C equivalent: [`TDEA_File`](#TDEA_File) [[Contents](#topofpage)] [[Index](#index)] --- ### Tdea.FileEncrypt Method (String, String, String, Mode, String) Encrypt a file passing key and IV as hex strings. #### Syntax [`C#`] ``` public static int FileEncrypt( string fileOut, string fileIn, string keyHex, Mode mode, string ivHex ) ``` [`VB.NET`] ``` Public Shared Function FileEncrypt ( _ fileOut As String, _ fileIn As String, _ keyHex As String, _ mode As Mode, _ ivHex As String _ ) As Integer ``` #### Parameters fileOut : Name of output file to be created or overwritten fileIn : Name of input file keyHex : Hex-encoded key of exact length mode : Type: [Mode](#T_Mode) Cipher Mode ivHex : Hex-encoded IV or "" for ECB mode #### Return Value 0 if successful or non-zero [error code](#errorcodes) #### Remarks fileOut and fileIn must **not** be the same. The output file is in binary format. [[Contents](#topofpage)] [[Index](#index)] --- ### Wipe.Data Method Zeroise data in memory. #### Syntax [`C#`] ``` public static bool Data( byte[] data ) ``` [`VB.NET`] ``` Public Shared Function Data ( _ data As Byte() _ ) As Boolean ``` #### Parameters data : data to be wiped #### Return Value true if successful; false if fails #### See Also VB6/C equivalent: [`WIPE_Data`](#WIPE_Data) [[Contents](#topofpage)] [[Index](#index)] --- ### Wipe.File Method Securely wipe and delete a file with options. #### Syntax [`C#`] ``` public static bool File( string fileName, Wipe.Options opts ) ``` [`VB.NET`] ``` Public Shared Function File ( _ fileName As String, _ opts As Wipe.Options _ ) As Boolean ``` #### Parameters fileName : Name of file to be wiped opts : Type: [Wipe.Options](#T_Wipe_Options) Options (optional, default = DOD 7-pass) #### Return Value true if successful; false if fails #### See Also VB6/C equivalent: [`WIPE_File`](#WIPE_File) [[Contents](#topofpage)] [[Index](#index)] --- ### Wipe.String Method Zeroise a StringBuilder. #### Syntax [`C#`] ``` public static bool String( StringBuilder sb ) ``` [`VB.NET`] ``` Public Shared Function String ( _ sb As StringBuilder _ ) As Boolean ``` #### Parameters sb : StringBuilder to be wiped #### Return Value true if successful; false if fails #### Remarks NB You can't wipe an ordinary string as they are immutable in C#, so store any sensitive string data in a StringBuilder. #### See Also VB6/C equivalent: [`WIPE_Data`](#WIPE_Data) [[Contents](#topofpage)] [[Index](#index)] --- ### X509.CertExpiresOn Method Return date and time certificate expires. #### Syntax [`C#`] ``` public static string CertExpiresOn( string certFile ) ``` [`VB.NET`] ``` Public Shared Function CertExpiresOn ( _ certFile As String _ ) As String ``` #### Parameters certFile : Filename of certificate file (or its base64 representation) #### Return Value Date and time in ISO format or Empty string if error #### See Also VB6/C equivalent: [`X509_CertExpiresOn`](#X509_CertExpiresOn) [[Contents](#topofpage)] [[Index](#index)] --- ### X509.CertIssuedOn Method Return date and time certificate was issued. #### Syntax [`C#`] ``` public static string CertIssuedOn( string certFile ) ``` [`VB.NET`] ``` Public Shared Function CertIssuedOn ( _ certFile As String _ ) As String ``` #### Parameters certFile : Filename of certificate file (or its base64 representation) #### Return Value Date and time in ISO format or Empty string if error #### See Also VB6/C equivalent: [`X509_CertIssuedOn`](#X509_CertIssuedOn) [[Contents](#topofpage)] [[Index](#index)] --- ### X509.CertIssuerName Method Get the issuer name of an X.509 certificate. #### Syntax [`C#`] ``` public static string CertIssuerName( string certFile, string delimiter ) ``` [`VB.NET`] ``` Public Shared Function CertIssuerName ( _ certFile As String, _ delimiter As String _ ) As String ``` #### Parameters certFile : Filename of certificate file (or its base64 representation) delimiter : Optional character for delimiter [default = semicolon ";"] #### Return Value Issuer name or Empty string if error #### Remarks Use X509.QueryCert with query "issuerName" for more output options. #### See Also VB6/C equivalent: [`X509_CertIssuerName`](#X509_CertIssuerName) [[Contents](#topofpage)] [[Index](#index)] --- ### X509.CertIsValidNow Method Verify that an X.509 certificate is currently valid as per system clock. #### Syntax [`C#`] ``` public static bool CertIsValidNow( string certFile ) ``` [`VB.NET`] ``` Public Shared Function CertIsValidNow ( _ certFile As String _ ) As Boolean ``` #### Parameters certFile : Filename of certificate file (or its base64 representation) #### Return Value True if certificate is currently valid, otherwise false #### See Also VB6/C equivalent: [`X509_CertIsValidNow`](#X509_CertIsValidNow) [[Contents](#topofpage)] [[Index](#index)] --- ### X509.CertRequest Method Create a PKCS #10 certificate signing request (CSR). #### Syntax [`C#`] ``` public static int CertRequest( string reqFile, string privateKeyFile, string distName, string extensions, string password, SigAlgorithm sigAlg, X509.CsrOptions opts ) ``` [`VB.NET`] ``` Public Shared Function CertRequest ( _ reqFile As String, _ privateKeyFile As String, _ distName As String, _ extensions As String, _ password As String, _ sigAlg As SigAlgorithm, _ opts As X509.CsrOptions _ ) As Integer ``` #### Parameters reqFile : Name of Certificate Signing Request file to be created privateKeyFile : Name of subject's encrypted private key file distName : Specifying the subject's distinguished name as a set of attribute key=value pairs separated with semi-colons (;). See Specifying Distinguished Names extensions : A list of attribute-value pairs to be included in an extensionRequest field. See X.509 Extensions password : password for Subject's encrypted private key file sigAlg : Type: [SigAlgorithm](#T_SigAlgorithm) Signature algorithm (must match key type) opts : Type: [X509.CsrOptions](#T_X509_CsrOptions) Option flags: set as zero for defaults. #### Return Value Zero if successful or a non-zero [error code](#errorcodes) #### Remarks An ECC key must use an ECDSA signature algorithm, and an RSA key must use an RSA signature algorithm. #### See Also VB6/C equivalent: [`X509_CertRequest`](#X509_CertRequest) [[Contents](#topofpage)] [[Index](#index)] --- ### X509.CertSerialNumber Method Return serial number in hex format. #### Syntax [`C#`] ``` public static string CertSerialNumber( string certFile ) ``` [`VB.NET`] ``` Public Shared Function CertSerialNumber ( _ certFile As String _ ) As String ``` #### Parameters certFile : Filename of certificate file (or its base64 representation) #### Return Value Serial number in hex format or Empty string if error #### See Also VB6/C equivalent: [`X509_CertSerialNumber`](#X509_CertSerialNumber) [[Contents](#topofpage)] [[Index](#index)] --- ### X509.CertSubjectName Method Get the subject name of an X.509 certificate. #### Syntax [`C#`] ``` public static string CertSubjectName( string certFile, string delimiter ) ``` [`VB.NET`] ``` Public Shared Function CertSubjectName ( _ certFile As String, _ delimiter As String _ ) As String ``` #### Parameters certFile : Filename of certificate file (or its base64 representation) delimiter : Optional character for delimiter [default = semicolon ";"] #### Return Value Subject name or Empty string if error #### Remarks Use X509.QueryCert with query "subjectName" for more output options. #### See Also VB6/C equivalent: [`X509_CertSubjectName`](#X509_CertSubjectName) [[Contents](#topofpage)] [[Index](#index)] --- ### X509.CertThumb Method Calculate the thumbprint (message digest hash) of an X.509 certificate. #### Syntax [`C#`] ``` public static string CertThumb( string certFile, HashAlgorithm hashAlg ) ``` [`VB.NET`] ``` Public Shared Function CertThumb ( _ certFile As String, _ hashAlg As HashAlgorithm _ ) As String ``` #### Parameters certFile : Filename of certificate file (or its base64 representation) hashAlg : Type: [HashAlgorithm](#T_HashAlgorithm) HashAlgorithm #### Return Value String containing the message digest in hexadecimal format #### See Also VB6/C equivalent: [`X509_CertThumb`](#X509_CertThumb) [[Contents](#topofpage)] [[Index](#index)] --- ### X509.CheckCertInCRL Method Check whether an X.509 certificate has been revoked in a Certificate Revocation List (CRL). #### Syntax [`C#`] ``` public static int CheckCertInCRL( string certFile, string crlFile, string issuerCert, string dateStr ) ``` [`VB.NET`] ``` Public Shared Function CheckCertInCRL ( _ certFile As String, _ crlFile As String, _ issuerCert As String, _ dateStr As String _ ) As Integer ``` #### Parameters certFile : name of X.509 certificate to be checked (or base64 representation) crlFile : name of CRL file issuerCert : (optional) with name of X.509 certificate file for the entity that issued the CRL (or base64 representation) dateStr : (optional) with date in ISO format (yyyy-mm-dd[Thh[:nn:ss]][Z]) on or after you wish to check for revocation. Leave empty "" for any date. The time must be in GMT (UTC, Zulu time) #### Return Value Zero if the certificate is NOT in the CRL; X509.Revoked (REVOCATION_ERROR +42) if the certificate has been revoked; otherwise a nonzero [error code](#errorcodes). #### Remarks The optional dateStr parameter allows you check whether a certificate was revoked only after the given date-time, which must be GMT (UTC). If the optional issuerCert is specified, the signature of the CRL will be checked against the key in the issuer's certificate and a SIGNATURE_ERROR will result if the signature is invalid. #### See Also VB6/C equivalent: [`X509_CheckCertInCRL`](#X509_CheckCertInCRL) [[Contents](#topofpage)] [[Index](#index)] --- ### X509.GetCertCountInP7Chain Method Return number of certificates in a PKCS-7 "certs-only" certificate chain file. #### Syntax [`C#`] ``` public static int GetCertCountInP7Chain( string inputFile ) ``` [`VB.NET`] ``` Public Shared Function GetCertCountInP7Chain ( _ inputFile As String _ ) As Integer ``` #### Parameters inputFile : Name of the PKCS-7 "certs-only" file, or a string containing its PEM textual representation. #### Return Value Number of X.509 certificates found or a negative [error code](#errorcodes). #### See Also VB6/C equivalent: [`X509_GetCertCountInP7Chain`](#X509_GetCertCountInP7Chain) [[Contents](#topofpage)] [[Index](#index)] --- ### X509.GetCertFromP7Chain Method Extract an X.509 certificate from a PKCS-7 "certs-only" certificate chain file, saving the output directly as a new file. #### Syntax [`C#`] ``` public static int GetCertFromP7Chain( string outputFile, string inputFile, int index ) ``` [`VB.NET`] ``` Public Shared Function GetCertFromP7Chain ( _ outputFile As String, _ inputFile As String, _ index As Integer _ ) As Integer ``` #### Parameters outputFile : Name of output file to be created inputFile : Name of the PKCS-7 "certs-only" file, or a string containing its PEM textual representation. index : specifying which certificate (1,2,...) in the chain to extract. #### Return Value If successful and index is greater than zero, it returns the number of bytes written to the output file, which may be zero if no certificate could be found at the given index. If an error occurred, it returns a negative [error code](#errorcodes). #### Remarks *[New in v12.2]* To find the number of certificates in the chain, use GetCertCountInP7Chain. The old (deprecated) way to find the count of certificates was to set index to zero. #### See Also VB6/C equivalent: [`X509_GetCertFromP7Chain`](#X509_GetCertFromP7Chain) [[Contents](#topofpage)] [[Index](#index)] --- ### X509.GetCertFromPFX Method Extract an X.509 certificate from a PKCS-12 PFX/.p12 file, saving the output directly as a new file. #### Syntax [`C#`] ``` public static int GetCertFromPFX( string outputFile, string inputFile, string password ) ``` [`VB.NET`] ``` Public Shared Function GetCertFromPFX ( _ outputFile As String, _ inputFile As String, _ password As String _ ) As Integer ``` #### Parameters outputFile : Name of output file to be created inputFile : Name of the PKCS-12 file, or a string containing its PEM textual representation. password : Password or "" if not encrypted (default="") #### Return Value If successful, it returns the number of bytes written to the output file; otherwise it returns a negative [error code](#errorcodes) #### Remarks Only supports weak 40-bit RC2 encryption for the certificate. #### See Also VB6/C equivalent: [`X509_GetCertFromPFX`](#X509_GetCertFromPFX) [[Contents](#topofpage)] [[Index](#index)] --- ### X509.GetP7ChainFromPFX Method Extract all X.509 certificates from a PKCS-12 PFX/.p12 file, saving the output directly as a new PKCS-7 "certs-only" certificate chain file. #### Syntax [`C#`] ``` public static int GetP7ChainFromPFX( string outputFile, string inputFile, string password ) ``` [`VB.NET`] ``` Public Shared Function GetP7ChainFromPFX ( _ outputFile As String, _ inputFile As String, _ password As String _ ) As Integer ``` #### Parameters outputFile : Name of output file to be created inputFile : Name of the PKCS-12 file, or a string containing its PEM textual representation. password : Password or "" if not encrypted #### Return Value If successful, it returns the number of bytes written to the output file; otherwise it returns a negative [error code](#errorcodes) #### Remarks Only supports weak 40-bit RC2 encryption for the certificate. #### See Also VB6/C equivalent: [`X509_GetCertFromPFX`](#X509_GetCertFromPFX) [[Contents](#topofpage)] [[Index](#index)] --- ### X509.HashIssuerAndSN Method Create a message digest of the Issuer's name and the cert serial number. #### Syntax [`C#`] ``` public static string HashIssuerAndSN( string certFile, HashAlgorithm algorithm ) ``` [`VB.NET`] ``` Public Shared Function HashIssuerAndSN ( _ certFile As String, _ algorithm As HashAlgorithm _ ) As String ``` #### Parameters certFile : Filename of certificate file (or its base64 representation) algorithm : Type: [HashAlgorithm](#T_HashAlgorithm) Hash algorithm to use [default = SHA-1] #### Return Value Message digest in hex format or Empty string if error #### Remarks This (should) give a unique identifier for any certificate #### See Also VB6/C equivalent: [`X509_HashIssuerAndSN`](#X509_HashIssuerAndSN) [[Contents](#topofpage)] [[Index](#index)] --- ### X509.KeyUsageFlags Method Returns a bitfield containing the keyUsage flags. #### Syntax [`C#`] ``` public static int KeyUsageFlags( string certFile ) ``` [`VB.NET`] ``` Public Shared Function KeyUsageFlags ( _ certFile As String _ ) As Integer ``` #### Parameters certFile : Filename of certificate file (or its base64 representation) #### Return Value If successful, it returns a positive integer containing the keyUsage flags; or 0 if no keyUsage flags are set; otherwise it returns a negative [error code](#errorcodes) #### Remarks See X509.KeyUsageOptions. #### See Also VB6/C equivalent: [`X509_KeyUsageFlags`](#X509_KeyUsageFlags) [[Contents](#topofpage)] [[Index](#index)] --- ### X509.MakeCert Method Create a new X.509 certificate using subject's public key and issuer's private key files with signature options. #### Syntax [`C#`] ``` public static int MakeCert( string certFile, string issuerCert, string subjectPubKeyFile, string issuerPriKeyFile, int certNum, int yearsValid, string distName, string extensions, X509.KeyUsageOptions keyUsageOptions, string password, SigAlgorithm sigAlg, X509.CertOptions options ) ``` [`VB.NET`] ``` Public Shared Function MakeCert ( _ certFile As String, _ issuerCert As String, _ subjectPubKeyFile As String, _ issuerPriKeyFile As String, _ certNum As Integer, _ yearsValid As Integer, _ distName As String, _ extensions As String, _ keyUsageOptions As X509.KeyUsageOptions, _ password As String, _ sigAlg As SigAlgorithm, _ options As X509.CertOptions _ ) As Integer ``` #### Parameters certFile : Name of file to be created issuerCert : Name of issuer's certificate file subjectPubKeyFile : File containing subjects public key data issuerPriKeyFile : File containing issuer's private key data certNum : Issue number for new certificate yearsValid : How many years to be valid distName : Distinguished name string. See Distinguished Names in the main manual. extensions : Extensions: a list of attribute-value pairs separated by semicolons (;). See X.509 Extensions Parameter in the main manual. keyUsageOptions : Type: [X509.KeyUsageOptions](#T_X509_KeyUsageOptions) Key usage options password : For issuer's private key, if encrypted. sigAlg : Type: [SigAlgorithm](#T_SigAlgorithm) Signature algorithm to sign certificate. options : Type: [X509.CertOptions](#T_X509_CertOptions) Option flags: set as zero for defaults. #### Return Value Zero if successful or a non-zero [error code](#errorcodes) #### Remarks Valid extensions are: | **rfc822Name**=string; | To set the rfc822 email address in the subjectAltName extension, e.g. rfc822Name=myname@testorg.com. | | --- | --- | | **serialNumber**=hex-digits; | To override the serial number set by certNum with a larger, unlimited integer in hexadecimal format, e.g. serialNumber=12deadbeefcafe0123. | | **subjectKeyIdentifier**=hex-digits; | To set the subjectAltName extension with an octet string (binary) value specified in hex format e.g. subjectKeyIdentifier=fedcba9876543210. | | **notAfter**=iso-date-string; | To override the validity period set by yearsValid with a specific date and time in ISO format, e.g. notAfter=2020-12-31 or notAfter=2020-12-31T14:03:59. If no time is given it will default to 23:59:59. Note that this time is UTC (GMT) not local. | | **notBefore**=iso-date-string; | To override the default start time from one minute ago to a specific date and time in ISO format, e.g. notBefore=2008-12-31. If no time is given it will default to 00:00:01. Note that this time is UTC (GMT) not local. | | ****=#; | Add an arbitrary X.509 version 3 Extension with typeID set to decoded and extnValue set to ASN.1 value encoded in . | As an alternative, you can create a new X.509 certificate using a PKCS-10 certificate signing request (CSR) file. Pass the name of the CSR file in the subjectPubkeyFile parameter and set the distName empty "". The empty distinguished name parameter is a flag that a CSR file is being used. #### See Also VB6/C equivalent: [`X509_MakeCert`](#X509_MakeCert) [[Contents](#topofpage)] [[Index](#index)] --- ### X509.MakeCertSelf Method Create a self-signed X.509 certificate with signature options. #### Syntax [`C#`] ``` public static int MakeCertSelf( string certFile, string privateKeyFile, int certNum, int yearsValid, string distName, string extensions, X509.KeyUsageOptions keyUsageOptions, string password, SigAlgorithm sigAlg, X509.CertOptions options ) ``` [`VB.NET`] ``` Public Shared Function MakeCertSelf ( _ certFile As String, _ privateKeyFile As String, _ certNum As Integer, _ yearsValid As Integer, _ distName As String, _ extensions As String, _ keyUsageOptions As X509.KeyUsageOptions, _ password As String, _ sigAlg As SigAlgorithm, _ options As X509.CertOptions _ ) As Integer ``` #### Parameters certFile : Name of file to be created privateKeyFile : File containing issuer's private key data certNum : Issue number for new certificate yearsValid : How many years to be valid distName : Distinguished name string. See Distinguished Names in the main manual. extensions : Extensions: a list of attribute-value pairs separated by semicolons (;). See X.509 Extensions Parameter in the main manual. keyUsageOptions : Type: [X509.KeyUsageOptions](#T_X509_KeyUsageOptions) Key usage options password : For issuer's private key sigAlg : Type: [SigAlgorithm](#T_SigAlgorithm) Signature algorithm to sign certificate. options : Type: [X509.CertOptions](#T_X509_CertOptions) Option flags: set as zero for defaults. #### Return Value Zero if successful or a non-zero [error code](#errorcodes) #### See Also VB6/C equivalent: [`X509_MakeCertSelf`](#X509_MakeCertSelf) [[Contents](#topofpage)] [[Index](#index)] --- ### X509.MakeCRL Method Create an X.509 Certificate Revocation List (CRL). #### Syntax [`C#`] ``` public static int MakeCRL( string crlFile, string issuerCert, string issuerKeyFile, string password, string revokedCertList, string extensions, SigAlgorithm sigAlg, X509.CrlOptions opts ) ``` [`VB.NET`] ``` Public Shared Function MakeCRL ( _ crlFile As String, _ issuerCert As String, _ issuerKeyFile As String, _ password As String, _ revokedCertList As String, _ extensions As String, _ sigAlg As SigAlgorithm, _ opts As X509.CrlOptions _ ) As Integer ``` #### Parameters crlFile : name of new CRL file to be created issuerCert : name of issuer's X.509 certificate file (or base64 representation) issuerKeyFile : name of issuer's encrypted private key file password : password for Issuer's encrypted private key file revokedCertList : list of revoked certificates in format serialNumber,revocationDate; ... or the empty string "" for no revoked certificates. See the Remarks section below for more details extensions : A list of attribute-value pairs separated by semicolons (;) or the empty string "". Valid attribute-value pairs are: * lastUpdate=*iso-date-string* * nextUpdate=*iso-date-string* sigAlg : Type: [SigAlgorithm](#T_SigAlgorithm) Signature algorithm. opts : Type: [X509.CrlOptions](#T_X509_CrlOptions) Options #### Return Value If successful, the return value is zero; otherwise it returns a non-zero [error code](#errorcodes). #### Remarks This creates a version 1 CRL file with no extensions or cRLReason's. The parameter revokedCertList must be in the form serialNumber,revocationDate;serialNumber,revocationDate; .... The serialNumber must either be a positive decimal integer (e.g. 123) or the number in hex format preceded by #x (e.g. #x0102deadbeef). The revocation date must be in ISO date format (e.g. 2009-12-31T12:59:59Z). For example, "1,2007-12-31; 2, 2009-12-31T12:59:59Z; 66000,2066-01-01; #x0102deadbeef,2010-02-28T01:01:59" By default, the lastUpdate time in the CRL is set to the time given by the system clock, and nextUpdate time is left empty. You can specify your own times using the lastUpdate and nextUpdate attributes in the extensions parameter. Times, if specified, must be in ISO 8601 format and are always interpreted as GMT times whether or not you add a "Z". #### See Also VB6/C equivalent: [`X509_MakeCRL`](#X509_MakeCRL) [[Contents](#topofpage)] [[Index](#index)] --- ### X509.QueryCert Method Query an X.509 certificate file for selected information. #### Syntax [`C#`] ``` public static string QueryCert( string certFile, string query, X509.OutputOpts outOpts ) ``` [`VB.NET`] ``` Public Shared Function QueryCert ( _ certFile As String, _ query As String, _ outOpts As X509.OutputOpts _ ) As String ``` #### Parameters certFile : Filename of certificate file (or its base64 representation) query : Query string (case insensitive) outOpts : Type: [X509.OutputOpts](#T_X509_OutputOpts) Optional options for output (default = 0) #### Return Value String containing the result, or an empty string if query not found or on error. #### Remarks Both binary BER and PEM-format certificates can be read, as can a base64 representation of the certificate. Valid queries are: | "version" | X.509 version number, e.g. "3". | | --- | --- | | "serialNumber" | Serial number in hex-encoded format. | | "signatureAlgorithm" | Signature algorithm used, e.g. "sha1WithRSAEncryption". | | "signatureValue" | Signature value in hex-encoded format. | | "notBefore" | Date on which the certificate validity period begins in ISO format yyyy-mm-ddThh:nn:ssZ | | "notAfter" | Date on which the certificate validity period ends in ISO format yyyy-mm-ddThh:nn:ssZ | | "issuerName" | Distinguished name (DN) of entity who has signed and issued the certificate. | | "subjectName" | Distinguished name (DN) of the subject. | | "subjectPublicKeyAlgorithm" | Algorithm used in subject's public key, e.g. "dsa". | | "subjectKeyIdentifier" | The subject key identifier extension, if present, in hex-encoded format. | | "authorityKeyIdentifier" | The authority key identifier extension, if present, in hex-encoded format. | | "rfc822Name" | Internet mail address contained in a subjectAltName extension, if present. | | "isCA" | Returns "1" if the subject type is a CA, otherwise returns "0". | | "keyUsageString" | keyUsage flags in text format, e.g. "digitalSignature,nonRepudiation". | | "extKeyUsageString" | extKeyUsage purposes in text format, e.g. "codeSigning,timeStamping". | | "cRLDistributionPointsURI" | First URI found in cRLDistributionPoints, if any. | | "authorityInfoAccessURI" | First URI found in authorityInfoAccess, if any. | | "subjectAltName" | Subject alternative name extension, if present. | | "hashAlgorithm" | Hash algorithm used in signature, e.g. "sha256". | | "pssParams" | Parameters used for RSA-PSS (if applicable). | #### See Also VB6/C equivalent: [`X509_QueryCert`](#X509_QueryCert) [[Contents](#topofpage)] [[Index](#index)] --- ### X509.ReadCertStringFromP7Chain Method Read an X.509 certificate into a base64 string from PKCS-7 "certs-only" data. #### Syntax [`C#`] ``` public static string ReadCertStringFromP7Chain( string inputFile, int index ) ``` [`VB.NET`] ``` Public Shared Function ReadCertStringFromP7Chain ( _ inputFile As String, _ index As Integer _ ) As String ``` #### Parameters inputFile : filename of a PKCS-7 "certs-only" file, or a string containing its PEM textual representation. index : specifying which certificate (1,2,...) in the chain to extract. #### Return Value String in continuous base64 format, or an empty string on error. #### Remarks *[New in v12.2]* To find the number of certificates in the chain, use GetCertCountInP7Chain. The old (deprecated) way to find the count of certificates was to set index to zero. #### See Also VB6/C equivalent: [`X509_ReadCertStringFromP7Chain`](#X509_ReadCertStringFromP7Chain) [[Contents](#topofpage)] [[Index](#index)] --- ### X509.ReadCertStringFromPFX Method Read an X.509 certificate into a base64 string from PKCS-12 PFX/.p12 data. #### Syntax [`C#`] ``` public static string ReadCertStringFromPFX( string inputFile, string password ) ``` [`VB.NET`] ``` Public Shared Function ReadCertStringFromPFX ( _ inputFile As String, _ password As String _ ) As String ``` #### Parameters inputFile : filename of a PFX file, or a string containing its PEM textual representation. password : password for PFX or "" if certificate is not encrypted #### Return Value String in continuous base64 format, or an empty string on error. #### Remarks Only supports weak 40-bit RC2 encryption for the certificate. #### See Also VB6/C equivalent: [`X509_ReadCertStringFromPFX`](#X509_ReadCertStringFromPFX) [[Contents](#topofpage)] [[Index](#index)] --- ### X509.ReadStringFromFile Method Create a base64 string representation of a X.509 certificate file. #### Syntax [`C#`] ``` public static string ReadStringFromFile( string certFile ) ``` [`VB.NET`] ``` Public Shared Function ReadStringFromFile ( _ certFile As String _ ) As String ``` #### Parameters certFile : Filename of certificate file (or its base64 representation) #### Return Value String in continuous base64 format, or an empty string on error. #### See Also VB6/C equivalent: [`X509_ReadStringFromFile`](#X509_ReadStringFromFile) [[Contents](#topofpage)] [[Index](#index)] --- ### X509.SaveFileFromString Method Create a new X.509 certificate file from a base64 string representation. #### Syntax [`C#`] ``` public static int SaveFileFromString( string newCertFile, string certString, bool inPEMFormat ) ``` [`VB.NET`] ``` Public Shared Function SaveFileFromString ( _ newCertFile As String, _ certString As String, _ inPEMFormat As Boolean _ ) As Integer ``` #### Parameters newCertFile : Name of new certificate file to be created. certString : String containing certificate data in base64 format. inPEMFormat : True to save in base64 PEM format, or false to save in binary DER format. #### Return Value Zero if successful or non-zero [error code](#errorcodes) #### Remarks Any existing file of the same name will be overwritten without warning. A PEM format file will start with -----BEGIN CERTIFICATE-----. #### See Also VB6/C equivalent: [`X509_SaveFileFromString`](#X509_SaveFileFromString) [[Contents](#topofpage)] [[Index](#index)] --- ### X509.TextDump Method Dump details of an X.509 certificate or a X.509 certificate revocation list (CRL) or a PKCS-10 certificate signing request (CSR) to a text file. #### Syntax [`C#`] ``` public static int TextDump( string outputFile, string certFile, X509.OutputOpts outOpts ) ``` [`VB.NET`] ``` Public Shared Function TextDump ( _ outputFile As String, _ certFile As String, _ outOpts As X509.OutputOpts _ ) As Integer ``` #### Parameters outputFile : Filename of text file to be created certFile : Filename of certificate file (or its base64 representation) outOpts : Type: [X509.OutputOpts](#T_X509_OutputOpts) Options for output (optional) #### Return Value If successful, the return value is zero; otherwise it returns a nonzero [error code](#errorcodes). #### Remarks The notation [!] denotes a critical extension, e.g. Key Usage[!]:. #### See Also VB6/C equivalent: [`X509_TextDump`](#X509_TextDump) [[Contents](#topofpage)] [[Index](#index)] --- ### X509.TextDumpToString Method Dump details of an X.509 certificate or a X.509 certificate revocation list (CRL) or a PKCS-10 certificate signing request (CSR) to a string. #### Syntax [`C#`] ``` public static string TextDumpToString( string certFile, X509.OutputOpts outOpts ) ``` [`VB.NET`] ``` Public Shared Function TextDumpToString ( _ certFile As String, _ outOpts As X509.OutputOpts _ ) As String ``` #### Parameters certFile : Filename of certificate file (or its base64 representation) outOpts : Type: [X509.OutputOpts](#T_X509_OutputOpts) Options for output #### Return Value String containing the result, or an empty string on error. #### Remarks The notation [!] denotes a critical extension, e.g. Key Usage[!]:. #### See Also VB6/C equivalent: [`X509_TextDumpToString`](#X509_TextDumpToString) [[Contents](#topofpage)] [[Index](#index)] --- ### X509.ValidatePath Method Validate a certificate path. #### Syntax [`C#`] ``` public static int ValidatePath( string certListOrP7File, string trustedCert, bool noTimeCheck ) ``` [`VB.NET`] ``` Public Shared Function ValidatePath ( _ certListOrP7File As String, _ trustedCert As String, _ noTimeCheck As Boolean _ ) As Integer ``` #### Parameters certListOrP7File : either a list of certificate names separated by a semicolon or the name of a PKCS-7 "certs-only" file containing the certificates to be validated trustedCert : (optional) name of the trusted certificate (or base64 representation) noTimeCheck : Set True to avoid checking if the certificates are valid now [default = check validity dates against system clock]. #### Return Value Zero if the certification path is valid; X509.Invalid (CERT_PATH_ERROR +43) if the path is invalid; otherwise a negative [error code](#errorcodes). #### See Also VB6/C equivalent: [`X509_ValidatePath`](#X509_ValidatePath) [[Contents](#topofpage)] [[Index](#index)] --- ### X509.VerifyCert Method Verify that an X.509 certificate has been signed by its issuer. #### Syntax [`C#`] ``` public static int VerifyCert( string certToVerify, string issuerCert ) ``` [`VB.NET`] ``` Public Shared Function VerifyCert ( _ certToVerify As String, _ issuerCert As String _ ) As Integer ``` #### Parameters certToVerify : Filename of certificate to verify issuerCert : Filename of purported issuer's certificate #### Return Value Zero if the certificate's signature is valid; X509.Failure (SIGNATURE_ERROR +22) if the validation fails; otherwise a positive [error code](#errorcodes). #### Remarks This can also be used to verify that an X.509 Certificate Revocation List (CRL) or PKCS#10 Certification Signing Request (CSR) has been signed by the owner of the issuer's certificate. Just pass the name of the file (or its base64/PEM string form) as certToVerify. #### See Also VB6/C equivalent: [`X509_VerifyCert`](#X509_VerifyCert) [[Contents](#topofpage)] [[Index](#index)] --- ### Xof.Bytes Method Generate bytes using an eXtendable-Output Function (XOF). #### Syntax [`C#`] ``` public static byte[] Bytes( int numBytes, byte[] message, Xof.Alg xofAlg ) ``` [`VB.NET`] ``` Public Shared Function Bytes ( _ numBytes As Integer, _ message As Byte(), _ xofAlg As Xof.Alg _ ) As Byte() ``` #### Parameters numBytes : Required number of output bytes. message : Input message data. xofAlg : Type: [Xof.Alg](#T_Xof_Alg) XOF algorithm. #### Return Value Output data in byte array. #### See Also VB6/C equivalent: [`XOF_Bytes`](#XOF_Bytes) [[Contents](#topofpage)] [[Index](#index)] --- Enumerations in .NET --------------------------------------------------- * [AeadAlgorithm Enumeration](#T_AeadAlgorithm) * [Asn1.Options Enumeration](#T_Asn1_Options) * [Cipher.Opts Enumeration](#T_Cipher_Opts) * [CipherAlgorithm Enumeration](#T_CipherAlgorithm) * [Cms.ComprDataOptions Enumeration](#T_Cms_ComprDataOptions) * [Cms.ContentEncrAlg Enumeration](#T_Cms_ContentEncrAlg) * [Cms.EnvDataOptions Enumeration](#T_Cms_EnvDataOptions) * [Cms.Format Enumeration](#T_Cms_Format) * [Cms.KeyEncrAlgorithm Enumeration](#T_Cms_KeyEncrAlgorithm) * [Cms.ReadOptions Enumeration](#T_Cms_ReadOptions) * [Cms.SigAlg Enumeration](#T_Cms_SigAlg) * [Cms.SigDataOptions Enumeration](#T_Cms_SigDataOptions) * [Cnv.EncodingConversion Enumeration](#T_Cnv_EncodingConversion) * [Cnv.EndianNess Enumeration](#T_Cnv_EndianNess) * [Ecc.CurveName Enumeration](#T_Ecc_CurveName) * [Ecc.Format Enumeration](#T_Ecc_Format) * [Ecc.KeyType Enumeration](#T_Ecc_KeyType) * [Ecc.PbeScheme Enumeration](#T_Ecc_PbeScheme) * [EncodingBase Enumeration](#T_EncodingBase) * [HashAlgorithm Enumeration](#T_HashAlgorithm) * [Hpke.AeadAlg Enumeration](#T_Hpke_AeadAlg) * [Hpke.CurveName Enumeration](#T_Hpke_CurveName) * [Hpke.OutputOpts Enumeration](#T_Hpke_OutputOpts) * [Kdf.HashAlg Enumeration](#T_Kdf_HashAlg) * [Kdf.KdfAlg Enumeration](#T_Kdf_KdfAlg) * [Kdf.KeyWrapAlg Enumeration](#T_Kdf_KeyWrapAlg) * [Mode Enumeration](#T_Mode) * [Padding Enumeration](#T_Padding) * [Pfx.Options Enumeration](#T_Pfx_Options) * [Prf.Alg Enumeration](#T_Prf_Alg) * [Rng.Options Enumeration](#T_Rng_Options) * [Rng.Strength Enumeration](#T_Rng_Strength) * [Rsa.AdvOptions Enumeration](#T_Rsa_AdvOptions) * [Rsa.EME Enumeration](#T_Rsa_EME) * [Rsa.Format Enumeration](#T_Rsa_Format) * [Rsa.HashAlg Enumeration](#T_Rsa_HashAlg) * [Rsa.PbeOptions Enumeration](#T_Rsa_PbeOptions) * [Rsa.PublicExponent Enumeration](#T_Rsa_PublicExponent) * [Rsa.XmlOptions Enumeration](#T_Rsa_XmlOptions) * [Sig.Encoding Enumeration](#T_Sig_Encoding) * [Sig.SigOptions Enumeration](#T_Sig_SigOptions) * [Sig.VerifyOpts Enumeration](#T_Sig_VerifyOpts) * [SigAlgorithm Enumeration](#T_SigAlgorithm) * [Smime.Options Enumeration](#T_Smime_Options) * [Wipe.Options Enumeration](#T_Wipe_Options) * [X509.CertOptions Enumeration](#T_X509_CertOptions) * [X509.CrlOptions Enumeration](#T_X509_CrlOptions) * [X509.CsrOptions Enumeration](#T_X509_CsrOptions) * [X509.KeyUsageOptions Enumeration](#T_X509_KeyUsageOptions) * [X509.OutputOpts Enumeration](#T_X509_OutputOpts) * [Xof.Alg Enumeration](#T_Xof_Alg) [[Contents](#topofpage)] [[Index](#index)] --- ### AeadAlgorithm Enumeration Authenticated encryption algorithm. #### Syntax [`C#`] ``` public enum AeadAlgorithm ``` [`VB.NET`] ``` Public Enumeration AeadAlgorithm ``` #### Members | | Member name | Description | | | Aes_128_Gcm | Use the AEAD_AES_128_GCM authenticated encryption algorithm from RFC 5116. | | | Aes_192_Gcm | Use the AES-192-GCM authenticated encryption algorithm in the same manner as RFC 5116. | | | Aes_256_Gcm | Use the AEAD_AES_256_GCM authenticated encryption algorithm from RFC 5116. | | | ChaCha20_Poly1305 | Use the AEAD_CHACHA20_POLY1305 authenticated encryption algorithm from RFC 8439. | [[Contents](#topofpage)] [[Index](#index)] --- ### Asn1.Options Enumeration Options for ASN.1 methods #### Syntax [`C#`] ``` [FlagsAttribute] public enum Options ``` [`VB.NET`] ``` _ Public Enumeration Options ``` #### Members | | Member name | Description | | | Default | Default options | | | NoComments | Hide the comments [default=show comments] | | | AddLevels | Show level numbers [default=hide level numbers] | [[Contents](#topofpage)] [[Index](#index)] --- ### CipherAlgorithm Enumeration Block Cipher Algorithm #### Syntax [`C#`] ``` public enum CipherAlgorithm ``` [`VB.NET`] ``` Public Enumeration CipherAlgorithm ``` #### Members | | Member name | Description | | | Tdea | Triple DES (TDEA, 3DES, des-ede3) | | | Aes128 | AES-128 | | | Aes192 | AES-192 | | | Aes256 | AES-256 | [[Contents](#topofpage)] [[Index](#index)] --- ### Cipher.Opts Enumeration Advanced options #### Syntax [`C#`] ``` [FlagsAttribute] public enum Opts ``` [`VB.NET`] ``` _ Public Enumeration Opts ``` #### Members | | Member name | Description | | | Default | Default options | | | PrefixIV | Prefix (prepend) the IV before the ciphertext in the output (ignored for ECB mode) | [[Contents](#topofpage)] [[Index](#index)] --- ### Cms.ComprDataOptions Enumeration Advanced options for CMS compressed-data objects #### Syntax [`C#`] ``` [FlagsAttribute] public enum ComprDataOptions ``` [`VB.NET`] ``` _ Public Enumeration ComprDataOptions ``` #### Members | | Member name | Description | | | Default | Default options. | | | NoInflate | Extract the compressed data as is without inflation. | [[Contents](#topofpage)] [[Index](#index)] --- ### Cms.ContentEncrAlg Enumeration Content encryption algorithm. #### Syntax [`C#`] ``` public enum ContentEncrAlg ``` [`VB.NET`] ``` Public Enumeration ContentEncrAlg ``` #### Members | | Member name | Description | | | Default | Default = Triple DES *CAUTION!* | | | Tdea | Triple DES (TDEA, 3DES, des-ede3) | | | Aes128 | AES-128 | | | Aes192 | AES-192 | | | Aes256 | AES-256 | | | Aes_128_Gcm | AES-128-GCM authenticated encryption algorithm from RFC5116. | | | Aes_192_Gcm | AES-192-GCM authenticated encryption algorithm in the same manner as RFC5116. | | | Aes_256_Gcm | AES-256-GCM authenticated encryption algorithm from RFC5116. | | | ChaCha20_Poly1305 | AEAD_CHACHA20_POLY1305 authenticated encryption algorithm from RFC8439. | #### Remarks New in [v22.0]. Supersedes CipherAlgorithm parameter. [[Contents](#topofpage)] [[Index](#index)] --- ### Cms.EnvDataOptions Enumeration Advanced options for CMS enveloped-data objects. #### Syntax [`C#`] ``` [FlagsAttribute] public enum EnvDataOptions ``` [`VB.NET`] ``` _ Public Enumeration EnvDataOptions ``` #### Members | | Member name | Description | | | None | Default options. | | | FormatBase64 | Encode output in base64 (default = binary). | | | AltAlgId | Use alternative (non-standard) alternative TeleTrusT Content Encryption Algorithm Identifier. | | | BigFile | Use to speed up the encryption of large files (binary file to binary file only). | | | Mgf1Sha1 | Force the MGF1 hash function to be SHA-1 (RSA-OAEP only, default = same as encoding hash function). | | | Authenticated | Use AES-GCM authenticated encryption instead of AES-CBC (redundant as of [v22.0]). | [[Contents](#topofpage)] [[Index](#index)] --- ### Cms.Format Enumeration Output format. #### Syntax [`C#`] ``` public enum Format ``` [`VB.NET`] ``` Public Enumeration Format ``` #### Members | | Member name | Description | | | Default | Default output format | | | Binary | Binary output (default) | | | FormatBase64 | Output is encoded in base64 (default = binary). | [[Contents](#topofpage)] [[Index](#index)] --- ### Cms.KeyEncrAlgorithm Enumeration Key encryption algorithm for key transport (ktri) technique #### Syntax [`C#`] ``` public enum KeyEncrAlgorithm ``` [`VB.NET`] ``` Public Enumeration KeyEncrAlgorithm ``` #### Members | | Member name | Description | | | Default | Default | | | Rsa_Pkcs1v1_5 | RSAES-PKCS-v1_5 (rsaEncryption) | | | Rsa_Oaep | RSAES-OAEP | [[Contents](#topofpage)] [[Index](#index)] --- ### Cms.ReadOptions Enumeration Options for reading CMS objects. #### Syntax [`C#`] ``` [FlagsAttribute] public enum ReadOptions ``` [`VB.NET`] ``` _ Public Enumeration ReadOptions ``` #### Members | | Member name | Description | | | None | Default options. | | | BigFile | Use to speed up the encryption of large files (binary file input only). | [[Contents](#topofpage)] [[Index](#index)] --- ### Cms.SigAlg Enumeration Signature algorithm for CMS signed-data objects. #### Syntax [`C#`] ``` public enum SigAlg ``` [`VB.NET`] ``` Public Enumeration SigAlg ``` #### Members | | Member name | Description | | | Default | Use default signature algorithm (rsa-sha1/sha1WithRSAEncryption) | | | Rsa_Sha1 | Use sha1WithRSAEncryption (rsa-sha1) signature algorithm [default] | | | Rsa_Sha224 | Use sha224WithRSAEncryption (rsa-sha224) signature algorithm | | | Rsa_Sha256 | Use sha256WithRSAEncryption (rsa-sha256) signature algorithm | | | Rsa_Sha384 | Use sha384WithRSAEncryption (rsa-sha384) signature algorithm | | | Rsa_Sha512 | Use sha512WithRSAEncryption (rsa-sha512) signature algorithm | | | Rsa_Md5 | Use md5WithRSAEncryption (rsa-md5) signature algorithm [legacy, not recommended] | | | Rsa_Pss_Sha1 | Use RSA-PSS signature algorithm with SHA-1 | | | Rsa_Pss_Sha224 | Use RSA-PSS signature algorithm with SHA-224 | | | Rsa_Pss_Sha256 | Use RSA-PSS signature algorithm with SHA-256 | | | Rsa_Pss_Sha384 | Use RSA-PSS signature algorithm with SHA-384 | | | Rsa_Pss_Sha512 | Use RSA-PSS signature algorithm with SHA-512 | | | Ecdsa_Sha1 | Use ecdsaWithSHA1 (ecdsa-sha1) signature algorithm | | | Ecdsa_Sha224 | Use ecdsaWithSHA224 (ecdsa-sha224) signature algorithm | | | Ecdsa_Sha256 | Use ecdsaWithSHA256 (ecdsa-sha256) signature algorithm | | | Ecdsa_Sha384 | Use ecdsaWithSHA384 (ecdsa-sha384) signature algorithm | | | Ecdsa_Sha512 | Use ecdsaWithSHA512 (ecdsa-sha512) signature algorithm | | | Ed25519 | Use Ed25519 signature algorithm [RFC8032] | | | Ed448 | Use Ed448 signature algorithm [RFC8032 | [[Contents](#topofpage)] [[Index](#index)] --- ### Cms.SigDataOptions Enumeration Advanced options for CMS signed-data objects #### Syntax [`C#`] ``` [FlagsAttribute] public enum SigDataOptions ``` [`VB.NET`] ``` _ Public Enumeration SigDataOptions ``` #### Members | | Member name | Description | | | Default | Default option | | | ExcludeCerts | Exclude X.509 certs from output. | | | ExcludeData | Exclude data from output. | | | CertsOnly | Create a "certs-only" PKCS#7 certficate chain. | | | IncludeAttributes | To add signed attributes (default = no signed attributes) including content-type and message-digest plus any more added below. | | | AddSignTime | Add signing time to the signed attributes (requires IncludeAttributes). | | | AddSmimeCapabilities | Add S/MIME capabilities to the signed attributes (requires IncludeAttributes). | | | AddSigningCertificate | Add an ESS Signing Certificate attribute to the signed attributes (requires IncludeAttributes). | | | AddAlgProtection | Add an Algorithm Protection Attribute [RFC6211] to the signed attributes (requires IncludeAttributes). | | | FormatBase64 | Create output/expect input in base64 format (default = binary). | | | NoOuter | Create a "naked" SignedData object with no outerContentInfo as permitted by PKCS#7 v1.6 (specialist option). | | | AltAlgId | Use alternative (non-standard) signature algorithm identifiers, e.g. 'sha1withRSAEncryption' instead of 'rsaEncryption'. | | | BigFile | Use to speed up the processing of large files. | | | Mgf1Sha1 | Force the MGF1 hash function to be SHA-1 (RSASSA-PSS only, default = same as encoding hash function). | | | Pss_SaltLenZero | Use a zero-length salt in an RSA-PSS signature (default = hLen the length of the digest output). | | | PseudoSig | Create/sign a "pseudo" SignedData object with dummy placeholder signature. | [[Contents](#topofpage)] [[Index](#index)] --- ### Cnv.EncodingConversion Enumeration Conversion directions for ByteEncoding. #### Syntax [`C#`] ``` public enum EncodingConversion ``` [`VB.NET`] ``` Public Enumeration EncodingConversion ``` #### Members | | Member name | Description | | | Utf8_From_Latin1 | Converts UTF-8-encoded bytes into Latin-1-encoded | | | Latin1_From_Utf8 | Converts Latin-1-encoded bytes into UTF-8-encoded | [[Contents](#topofpage)] [[Index](#index)] --- ### Cnv.EndianNess Enumeration Byte order. #### Syntax [`C#`] ``` public enum EndianNess ``` [`VB.NET`] ``` Public Enumeration EndianNess ``` #### Members | | Member name | Description | | | BigEndian | Most-significant byte first | | | LittleEndian | Least-significant byte first | [[Contents](#topofpage)] [[Index](#index)] --- ### Ecc.CurveName Enumeration Supported curve names. #### Syntax [`C#`] ``` public enum CurveName ``` [`VB.NET`] ``` Public Enumeration CurveName ``` #### Members | | Member name | Description | | | Secp192r1 | NIST curve P-192 | | | Secp224r1 | NIST curve P-224 | | | Secp256r1 | NIST curve P-256 | | | Secp384r1 | NIST curve P-384 | | | Secp521r1 | NIST curve P-521 | | | Secp256k1 | "Bitcoin" curve | | | P_192 | NIST curve P-192 (synonym for secp192r1) | | | P_224 | NIST curve P-256 (synonym for secp256r1) | | | P_256 | NIST curve P-224 (synonym for secp224r1) | | | P_384 | NIST curve P-384 (synonym for secp384r1) | | | P_521 | NIST curve P-521 (synonym for secp521r1) | | | Prime192v1 | Alternative name for NIST curve P-192 | | | Prime256v1 | Alternative name for NIST curve P-256 | | | BrainpoolP256r1 | ECC Brainpool curve [RFC5639] | | | BrainpoolP384r1 | ECC Brainpool curve [RFC5639] | | | BrainpoolP512r1 | ECC Brainpool curve [RFC5639] | | | Ed25519 | Safe curve for EdDSA | | | Ed448 | Safe curve for EdDSA | | | X25519 | Safe curve for ECDH | | | X448 | Safe curve for ECDH | [[Contents](#topofpage)] [[Index](#index)] --- ### Ecc.Format Enumeration Format for output files. #### Syntax [`C#`] ``` public enum Format ``` [`VB.NET`] ``` Public Enumeration Format ``` #### Members | | Member name | Description | | | Default | Default = binary | | | Binary | Binary DER-encoded | | | PEM | PEM-encoded text file | [[Contents](#topofpage)] [[Index](#index)] --- ### Ecc.KeyType Enumeration Key type for unencrypted key file. #### Syntax [`C#`] ``` public enum KeyType ``` [`VB.NET`] ``` Public Enumeration KeyType ``` #### Members | | Member name | Description | | | Default | Save key in the default format. | | | Pkcs8PrivateKeyInfo | Save a NIST/SEC curve private key in PKCS#8 PrivateKeyInfo format (ignored for a public key) | | | Legacy | Save a safe private key in "legacy" PKCS#8 v1 format (default is v2 OneAsymmetricKey) | | | PrivateKey | Key value represents a private key (use for reading safe curves) | | | PublicKey | Key value represents a public key (use for reading safe curves) | [[Contents](#topofpage)] [[Index](#index)] --- ### Ecc.PbeScheme Enumeration Password-based encryption scheme to encrypt the private key file. #### Syntax [`C#`] ``` public enum PbeScheme ``` [`VB.NET`] ``` Public Enumeration PbeScheme ``` #### Members | | Member name | Description | | | Default | Default option (pbeWithSHAAnd3-KeyTripleDES-CBC) | | | PbeWithSHAAnd_KeyTripleDES_CBC | pbeWithSHAAnd3-KeyTripleDES-CBC from PKCS#12 | | | Pbe_Pbkdf2_des_EDE3_CBC | "pkcs5PBES2" with key derivation function "pkcs5PBKDF2" and encryption scheme "des-EDE3-CBC" | | | Pbe_Pbkdf2_aes128_CBC | "pkcs5PBES2" with key derivation function "pkcs5PBKDF2" and encryption scheme "aes128-CBC" | | | Pbe_Pbkdf2_aes192_CBC | "pkcs5PBES2" with key derivation function "pkcs5PBKDF2" and encryption scheme "aes192-CBC" | | | Pbe_Pbkdf2_aes256_CBC | "pkcs5PBES2" with key derivation function "pkcs5PBKDF2" and encryption scheme "aes256-CBC" | [[Contents](#topofpage)] [[Index](#index)] --- ### EncodingBase Enumeration Base for encoding methods #### Syntax [`C#`] ``` public enum EncodingBase ``` [`VB.NET`] ``` Public Enumeration EncodingBase ``` #### Members | | Member name | Description | | | Base64 | Base64 encoding | | | Base16 | Base16 encoding (i.e. hexadecimal) | [[Contents](#topofpage)] [[Index](#index)] --- ### HashAlgorithm Enumeration Message Digest Hash Algorithm #### Syntax [`C#`] ``` public enum HashAlgorithm ``` [`VB.NET`] ``` Public Enumeration HashAlgorithm ``` #### Members | | Member name | Description | | | Sha1 | SHA-1 (as per FIPS PUB 180-4) | | | Md5 | MD5 (as per RFC 1321) [legacy, not recommended] | | | Md2 | MD2 (as per RFC 1319) [legacy, definitely not recommended] | | | Sha224 | SHA-224 (as per FIPS PUB 180-4) | | | Sha256 | SHA-256 (as per FIPS PUB 180-4) | | | Sha384 | SHA-384 (as per FIPS PUB 180-4) | | | Sha512 | SHA-512 (as per FIPS PUB 180-4) | | | Sha3_224 | SHA-3-224 (as per FIPS PUB 202) | | | Sha3_256 | SHA-3-256 (as per FIPS PUB 202) | | | Sha3_384 | SHA-3-384 (as per FIPS PUB 202) | | | Sha3_512 | SHA-3-256 (as per FIPS PUB 202) | | | Ripemd160 | RIPEMD-160 | | | Bitcoin160 | RIPEMD-160 hash of a SHA-256 hash (RIPEMD160(SHA256(m))) | [[Contents](#topofpage)] [[Index](#index)] --- ### Hpke.AeadAlg Enumeration AEAD functions supported for HPKE #### Syntax [`C#`] ``` public enum AeadAlg ``` [`VB.NET`] ``` Public Enumeration AeadAlg ``` #### Members | | Member name | Description | | | None | No AEAD algorithm. | | | Aes_128_Gcm | Use the AEAD_AES_128_GCM authenticated encryption algorithm from RFC5116. | | | Aes_256_Gcm | Use the AEAD_AES_256_GCM authenticated encryption algorithm from RFC5116. | | | ChaCha20_Poly1305 | Use the AEAD_CHACHA20_POLY1305 authenticated encryption algorithm from RFC8439. | [[Contents](#topofpage)] [[Index](#index)] --- ### Hpke.CurveName Enumeration Supported ECDH curves for HPKE #### Syntax [`C#`] ``` public enum CurveName ``` [`VB.NET`] ``` Public Enumeration CurveName ``` #### Members | | Member name | Description | | | P_256 | NIST curve P-256 | | | P_384 | NIST curve P-384 | | | P_521 | NIST curve P-521 | | | X25519 | ECDH curve X25519 from RFC7748 | | | X448 | ECDH curve X448 from RFC7748 | [[Contents](#topofpage)] [[Index](#index)] --- ### Hpke.OutputOpts Enumeration Options to format or re-encode output. #### Syntax [`C#`] ``` public enum OutputOpts ``` [`VB.NET`] ``` Public Enumeration OutputOpts ``` #### Members | | Member name | Description | | | Default | Default = output as ephemeral "internal" key string. | | | KeyAsHex | Output key in hex format compatible with test vectors in [RFC9180] | [[Contents](#topofpage)] [[Index](#index)] --- ### Kdf.HashAlg Enumeration Hash algorithms for KDF #### Syntax [`C#`] ``` public enum HashAlg ``` [`VB.NET`] ``` Public Enumeration HashAlg ``` #### Members | | Member name | Description | | | Sha1 | SHA-1 (as per FIPS PUB 180-4) | | | Sha224 | SHA-224 (as per FIPS PUB 180-4) | | | Sha256 | SHA-256 (as per FIPS PUB 180-4) | | | Sha384 | SHA-384 (as per FIPS PUB 180-4) | | | Sha512 | SHA-512 (as per FIPS PUB 180-4) | [[Contents](#topofpage)] [[Index](#index)] --- ### Kdf.KdfAlg Enumeration Key derivation functions #### Syntax [`C#`] ``` public enum KdfAlg ``` [`VB.NET`] ``` Public Enumeration KdfAlg ``` #### Members | | Member name | Description | | | X963 | ANSI-X9.63-KDF key derivation function (default) | | | Hkdf | HMAC-based Key Derivation Function (HKDF) from [RFC5869] | [[Contents](#topofpage)] [[Index](#index)] --- ### Kdf.KeyWrapAlg Enumeration Key wrap algorithms for KDF #### Syntax [`C#`] ``` public enum KeyWrapAlg ``` [`VB.NET`] ``` Public Enumeration KeyWrapAlg ``` #### Members | | Member name | Description | | | Default | Default for Cms.MakeEnvData only. | | | Cms3DESwrap | Triple-DES Key Wrap algorithm from [RFC3217] | | | Aes128_wrap | AES-128 key wrap from [RFC3394] | | | Aes192_wrap | AES-192 key wrap from [RFC3394] | | | Aes256_wrap | AES-256 key wrap from [RFC3394] | [[Contents](#topofpage)] [[Index](#index)] --- ### Mode Enumeration Cipher Mode #### Syntax [`C#`] ``` public enum Mode ``` [`VB.NET`] ``` Public Enumeration Mode ``` #### Members | | Member name | Description | | | ECB | Electronic Code Book mode | | | CBC | Cipher Block Chaining mode | | | OFB | Output Feedback mode | | | CFB | Cipher Feedback mode | | | CTR | Counter mode | | | GCM | Galois/Counter mode (AES only) | [[Contents](#topofpage)] [[Index](#index)] --- ### Padding Enumeration Block Cipher Padding #### Syntax [`C#`] ``` public enum Padding ``` [`VB.NET`] ``` Public Enumeration Padding ``` #### Members | | Member name | Description | | | Default | Use default padding | | | NoPad | No padding is added | | | Pkcs5 | The padding scheme described in PKCS#5/#7 | | | OneAndZeroes | Pad with 0x80 followed by as many zero bytes necessary to fill the block | | | AnsiX923 | The padding scheme described in ANSI X9.23 | | | W3CPadding | The padding scheme described in W3C https://www.w3.org/TR/xmlenc-core1/#sec-Padding | [[Contents](#topofpage)] [[Index](#index)] --- ### Pfx.Options Enumeration Specialist options. #### Syntax [`C#`] ``` [FlagsAttribute] public enum Options ``` [`VB.NET`] ``` _ Public Enumeration Options ``` #### Members | | Member name | Description | | | Default | Default options: re-encrypt private key with "TripleDES-SHA1", encrypt certificate with 40-bit RC2, output in DER binary form. | | | PlainCert | Store the certificate in unencrypted form (default is encrypted with 40-bit RC2). | | | StrongCert | Encrypt the certificate with "stronger" TripleDES-SHA1 (default is "weak" 40-bit RC2). | | | CloneKey | Store the private key in the exact form of the pkcs-8 input file (default is to re-encrypt with Triple DES). | | | Aes256_Sha256 | Override other encryption options and encrypt both the private key and certificate using "AES256-SHA256" | | | DoubleEncrypt | Double-encrypt the private key (specialist option). | | | AltFormat | Create a PFX file with the exact peculiarities used by Microsoft (default is OpenSSL). | | | FormatPem | Create the output file in PEM format (default is DER-encoded binary). | [[Contents](#topofpage)] [[Index](#index)] --- ### Prf.Alg Enumeration Pseudorandom function (PRF) algorithm. #### Syntax [`C#`] ``` public enum Alg ``` [`VB.NET`] ``` Public Enumeration Alg ``` #### Members | | Member name | Description | | | Kmac128 | KMAC128 as per NIST SP 800-185 | | | Kmac256 | KMAC256 as per NIST SP 800-185 | [[Contents](#topofpage)] [[Index](#index)] --- ### Rng.Options Enumeration Rng options #### Syntax [`C#`] ``` public enum Options ``` [`VB.NET`] ``` Public Enumeration Options ``` #### Members | | Member name | Description | | | Default | Default option | | | NoIntelDrng | Turn off support for INTEL(R) DRNG for the current session. | [[Contents](#topofpage)] [[Index](#index)] --- ### Rng.Strength Enumeration Required security strength for user-prompted entropy #### Syntax [`C#`] ``` public enum Strength ``` [`VB.NET`] ``` Public Enumeration Strength ``` #### Members | | Member name | Description | | | Default | Default option | | | Bits_112 | 112 bits of security (default) | | | Bits_128 | 128 bits of security | | | Bits_192 | 192 bits of security | | | Bits_256 | 256 bits of security | [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.AdvOptions Enumeration Advanced options. #### Syntax [`C#`] ``` [FlagsAttribute] public enum AdvOptions ``` [`VB.NET`] ``` _ Public Enumeration AdvOptions ``` #### Members | | Member name | Description | | | Default | Default options. | | | Mgf1_Sha1 | Force the MGF hash function to be SHA-1 (OAEP only, default = same as encoding set by Rsa.HashAlg) | [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.EME Enumeration Encoding method for encryption. #### Syntax [`C#`] ``` public enum EME ``` [`VB.NET`] ``` Public Enumeration EME ``` #### Members | | Member name | Description | | | PKCSv1_5 | EME-PKCS1-v1_5 encoding method | | | OAEP | EME-OAEP encoding method | #### Remarks See PKCS#1 v2.2 [RFC8017] [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.Format Enumeration Format for saved RSA key. #### Syntax [`C#`] ``` public enum Format ``` [`VB.NET`] ``` Public Enumeration Format ``` #### Members | | Member name | Description | | | Default | Default = Binary | | | Binary | Binary DER-encoded | | | PEM | PEM Format | | | SSL | PEM format compatible with OpenSSL | [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.HashAlg Enumeration Hash function for OAEP encoding. #### Syntax [`C#`] ``` public enum HashAlg ``` [`VB.NET`] ``` Public Enumeration HashAlg ``` #### Members | | Member name | Description | | | Sha1 | SHA-1 (default) | | | Sha224 | SHA-224 | | | Sha256 | SHA-256 | | | Sha384 | SHA-384 | | | Sha512 | SHA-512 | [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.PbeOptions Enumeration Password-based encryption scheme to be used to encrypt the private key file. #### Syntax [`C#`] ``` public enum PbeOptions ``` [`VB.NET`] ``` Public Enumeration PbeOptions ``` #### Members | | Member name | Description | | | Default | Default option (pbeWithSHAAnd3-KeyTripleDES-CBC) | | | PbeWithSHAAnd_KeyTripleDES_CBC | pbeWithSHAAnd3-KeyTripleDES-CBC from PKCS#12 | | | Pbe_Pbkdf2_des_EDE3_CBC | "pkcs5PBES2" with key derivation function "pkcs5PBKDF2" and encryption scheme "des-EDE3-CBC" | | | Pbe_Pbkdf2_aes128_CBC | "pkcs5PBES2" with key derivation function "pkcs5PBKDF2" and encryption scheme "aes128-CBC" | | | Pbe_Pbkdf2_aes192_CBC | "pkcs5PBES2" with key derivation function "pkcs5PBKDF2" and encryption scheme "aes192-CBC" | | | Pbe_Pbkdf2_aes256_CBC | "pkcs5PBES2" with key derivation function "pkcs5PBKDF2" and encryption scheme "aes256-CBC" | | | PbeWithMD5AndDES_CBC | pbeWithMD5AndDES-CBC [legacy, not recommended for new implementations] | | | PbeWithMD2AndDES_CBC | pbeWithMD2AndDES-CBC [legacy, not recommended for new implementations] | | | PbeWithSHA1AndDES_CBC | pbeWithSHA1AndDES-CBC [legacy, not recommended for new implementations] | | | Pkcs5PBES2_des_EDE3_CBC | "pkcs5PBES2" with "pkcs5PBKDF2" and "des-EDE3-CBC" [Synonym retained for backwards compatibility] | [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.PublicExponent Enumeration Choices for public exponent (e) #### Syntax [`C#`] ``` public enum PublicExponent ``` [`VB.NET`] ``` Public Enumeration PublicExponent ``` #### Members | | Member name | Description | | | Exp_EQ_3 | Set exponent equal to 3 (F0) | | | Exp_EQ_5 | Set exponent equal to 5 (F1) | | | Exp_EQ_17 | Set exponent equal to 17 (F2) | | | Exp_EQ_257 | Set exponent equal to 257 (F3) | | | Exp_EQ_65537 | Set exponent equal to 65537 (F4) | #### Remarks Fermat Number F(x) = 2^(2^x) + 1. F0 to F4 are prime. [[Contents](#topofpage)] [[Index](#index)] --- ### Rsa.XmlOptions Enumeration Options when converting between internal RSA key and XML. #### Syntax [`C#`] ``` [FlagsAttribute] public enum XmlOptions ``` [`VB.NET`] ``` _ Public Enumeration XmlOptions ``` #### Members | | Member name | Description | | | ExcludePrivateParams | Exclude private key parameters | | | ForceRSAKeyValue | Create XML in .NET-compatible RSAKeyValue format (ToXML only) | | | HexBinaryFormat | Create XML in non-standard hex format (ToXML only) | | | RequirePrivate | Require private key to exist in the XML input or fail (FromXML only) | [[Contents](#topofpage)] [[Index](#index)] --- ### SigAlgorithm Enumeration Signature algorithm #### Syntax [`C#`] ``` public enum SigAlgorithm ``` [`VB.NET`] ``` Public Enumeration SigAlgorithm ``` #### Members | | Member name | Description | | | Default | Use default signature algorithm [rsa-sha1/sha1WithRSAEncryption] | | | Rsa_Sha1 | Use sha1WithRSAEncryption (rsa-sha1) signature algorithm [default] | | | Rsa_Sha224 | Use sha224WithRSAEncryption (rsa-sha224) signature algorithm | | | Rsa_Sha256 | Use sha256WithRSAEncryption (rsa-sha256) signature algorithm | | | Rsa_Sha384 | Use sha384WithRSAEncryption (rsa-sha384) signature algorithm | | | Rsa_Sha512 | Use sha512WithRSAEncryption (rsa-sha512) signature algorithm | | | Rsa_Md5 | Use md5WithRSAEncryption (rsa-md5) signature algorithm [legacy, not recommended] | | | Rsa_Pss_Sha1 | Use RSA-PSS signature algorithm with SHA-1 | | | Rsa_Pss_Sha224 | Use RSA-PSS signature algorithm with SHA-224 | | | Rsa_Pss_Sha256 | Use RSA-PSS signature algorithm with SHA-256 | | | Rsa_Pss_Sha384 | Use RSA-PSS signature algorithm with SHA-384 | | | Rsa_Pss_Sha512 | Use RSA-PSS signature algorithm with SHA-512 | | | Ecdsa_Sha1 | Use ecdsaWithSHA1 (ecdsa-sha1) signature algorithm | | | Ecdsa_Sha224 | Use ecdsaWithSHA224 (ecdsa-sha224) signature algorithm | | | Ecdsa_Sha256 | Use ecdsaWithSHA256 (ecdsa-sha256) signature algorithm | | | Ecdsa_Sha384 | Use ecdsaWithSHA384 (ecdsa-sha384) signature algorithm | | | Ecdsa_Sha512 | Use ecdsaWithSHA512 (ecdsa-sha512) signature algorithm | | | Ed25519 | Use Ed25519 signature algorithm | | | Ed448 | Use Ed448 signature algorithm | [[Contents](#topofpage)] [[Index](#index)] --- ### Sig.Encoding Enumeration Encodings for signature output. #### Syntax [`C#`] ``` public enum Encoding ``` [`VB.NET`] ``` Public Enumeration Encoding ``` #### Members | | Member name | Description | | | Default | Default encoding (base64) | | | Base64 | Base64 encoding (default) | | | Base64url | URL-safe base64 encoding as in section 5 of [RFC4648] | | | Base16 | Base16 encoding (i.e. hexadecimal) | [[Contents](#topofpage)] [[Index](#index)] --- ### Sig.SigOptions Enumeration Specialist options for signatures. #### Syntax [`C#`] ``` [FlagsAttribute] public enum SigOptions ``` [`VB.NET`] ``` _ Public Enumeration SigOptions ``` #### Members | | Member name | Description | | | Default | Use default options for signature. | | | UseDeterministic | ECDSA only: Use the deterministic digital signature generation procedure of [RFC6979] for ECDSA signature [default=random k]. | | | Asn1DERStructure | ECDSA only: Form ECDSA signature value as a DER-encoded ASN.1 structure [default=r||s]. | | | PssSaltLenHlen | RSA-PSS only: Set the salt length to hLen, the length of the output of the hash function [default]. | | | PssSaltLenMax | RSA-PSS only: Set the salt length to the maximum possible (like OpenSSL). | | | PssSaltLen20 | RSA-PSS only: Set the salt length to be exactly 20 bytes regardless of the hash algorithm. | | | PssSaltLenZero | RSA-PSS only: Set the salt length to be zero. | | | Mgf1Sha1 | RSA-PSS only: Force the MGF hash function to be SHA-1 [default = same as signature hash algorithm] | [[Contents](#topofpage)] [[Index](#index)] --- ### Sig.VerifyOpts Enumeration Specialist options for verifying a signature. #### Syntax [`C#`] ``` [FlagsAttribute] public enum VerifyOpts ``` [`VB.NET`] ``` _ Public Enumeration VerifyOpts ``` #### Members | | Member name | Description | | | Default | Use default options. | | | Mgf1Sha1 | RSA-PSS only: Force the MGF hash function to be SHA-1 [default = same as signature hash algorithm] | [[Contents](#topofpage)] [[Index](#index)] --- ### Smime.Options Enumeration Options for S/MIME methods #### Syntax [`C#`] ``` [FlagsAttribute] public enum Options ``` [`VB.NET`] ``` _ Public Enumeration Options ``` #### Members | | Member name | Description | | | Default | Default options | | | EncodeBase64 | Encode output in base64 | | | EncodeBinary | Encode body in binary encoding | | | AddX | Add an "x-" to the content subtype (for compatibility with legacy applications) | [[Contents](#topofpage)] [[Index](#index)] --- ### Wipe.Options Enumeration Wipe options. #### Syntax [`C#`] ``` public enum Options ``` [`VB.NET`] ``` Public Enumeration Options ``` #### Members | | Member name | Description | | | Default | Default options (DOD 7-pass) | | | Dod7Pass | DOD 7-pass (default) | | | Simple | Overwrite with single pass of zero bytes (quicker but less secure). | [[Contents](#topofpage)] [[Index](#index)] --- ### X509.CertOptions Enumeration Options to create X.509 certificate. #### Syntax [`C#`] ``` [FlagsAttribute] public enum CertOptions ``` [`VB.NET`] ``` _ Public Enumeration CertOptions ``` #### Members | | Member name | Description | | | Default | Default options | | | FormatPem | Create in PEM-encoded text file [default = binary DER-encoded] | | | UTF8String | Encode distinguished name as UTF8String [default = PrintableString] | | | NoBasicConstraints | Disable the BasicConstraints extension [default = include] | | | SetAsCA | Set the BasicConstraints subject type to be a CA [default = End Entity] | | | VersionOne | Create a Version 1 certificate, i.e. no extensions [default = Version 3] | | | AuthKeyId | Add the issuer's KeyIdentifier, if present, as an AuthorityKeyIdentifer [default = do not add] | | | Pss_SaltLenZero | Use a zero-length salt in an RSA-PSS signature [default = hLen the length of the digest output] | | | Ecdsa_Deterministic | Use the deterministic digital signature generation procedure of [RFC6979] for an ECDSA signature. | [[Contents](#topofpage)] [[Index](#index)] --- ### X509.CrlOptions Enumeration Options to create Certificate Revocation List (CRL) #### Syntax [`C#`] ``` [FlagsAttribute] public enum CrlOptions ``` [`VB.NET`] ``` _ Public Enumeration CrlOptions ``` #### Members | | Member name | Description | | | Default | Default options | | | FormatPem | Create in PEM-encoded text file [default = binary DER-encoded] | | | Pss_SaltLenZero | Use a zero-length salt in an RSA-PSS signature [default = hLen the length of the digest output] | | | Ecdsa_Deterministic | Use the deterministic digital signature generation procedure of [RFC6979] for an ECDSA signature. | [[Contents](#topofpage)] [[Index](#index)] --- ### X509.CsrOptions Enumeration Options to create PKCS#10 certificate signing request (CSR) #### Syntax [`C#`] ``` [FlagsAttribute] public enum CsrOptions ``` [`VB.NET`] ``` _ Public Enumeration CsrOptions ``` #### Members | | Member name | Description | | | Default | Default options | | | FormatBinary | Create in binary format [default = PEM-encoded text file] | | | UTF8String | Encode distinguished name as UTF8String [default = PrintableString] | | | RequestKludge | Create a request with the "kludge" that omits the strictly mandatory attributes completely [default = include attributes with zero-length field] | | | Pss_SaltLenZero | Use a zero-length salt in an RSA-PSS signature [default = hLen the length of the digest output] | | | Ecdsa_Deterministic | Use the deterministic digital signature generation procedure of [RFC6979] for an ECDSA signature. | [[Contents](#topofpage)] [[Index](#index)] --- ### X509.KeyUsageOptions Enumeration Options for key usage in certificate #### Syntax [`C#`] ``` [FlagsAttribute] public enum KeyUsageOptions ``` [`VB.NET`] ``` _ Public Enumeration KeyUsageOptions ``` #### Members | | Member name | Description | | | None | Key usage extension is not included. | | | DigitalSignature | subject public key is used for verifying digital signatures. | | | NonRepudiation | subject public key is used to verify digital signatures used to provide a non-repudiation service. | | | KeyEncipherment | subject public key is used for enciphering private or secret keys, i.e., for key transport. | | | DataEncipherment | subject public key is used for directly enciphering raw user data (uncommon). | | | KeyAgreement | subject public key is used for key agreement. | | | KeyCertSign | subject public key is used for verifying signatures on public key certificates. | | | CrlSign | subject public key is used for verifying signatures on certificate revocation lists. | | | EncipherOnly | subject public key may be used only for enciphering data while performing key agreement (only if keyAgreement bit is also set). | | | DecipherOnly | subject public key may be used only for deciphering data while performing key agreement (only if keyAgreement bit is also set). | #### Remarks Reference: [RFC5280] s4.2.1.3 Key Usage [[Contents](#topofpage)] [[Index](#index)] --- ### X509.OutputOpts Enumeration Options to format or re-encode output. #### Syntax [`C#`] ``` [FlagsAttribute] public enum OutputOpts ``` [`VB.NET`] ``` _ Public Enumeration OutputOpts ``` #### Members | | Member name | Description | | | Default | Default options | | | Latin1 | Encode distinguished name in Latin-1 encoding, if possible. | | | Unicode | Output distinguished name in Unicode character set (UTF-8 or UTF-16 as appropriate). | | | Ldap | Output distinguished name in LDAP string representation. | | | Decimal | Output serial number in decimal format [default = hex]. | [[Contents](#topofpage)] [[Index](#index)] --- ### Xof.Alg Enumeration eXtendable-Output Function (XOF) algorithm. #### Syntax [`C#`] ``` public enum Alg ``` [`VB.NET`] ``` Public Enumeration Alg ``` #### Members | | Member name | Description | | | Shake128 | SHAKE128 (as per FIPS PUB 202) | | | Shake256 | SHAKE256 (as per FIPS PUB 202) | | | Mgf1_Sha1 | MGF1-SHA-1 (as per PKCS#1) | | | Mgf1_Sha256 | MGF1-SHA-256 (as per PKCS#1) | | | Mgf1_Sha512 | MGF1-SHA-512 (as per PKCS#1) | [[Contents](#topofpage)] [[Index](#index)] --- Error Handling and Error Codes ----------------------------------------------------- ### Error Codes ``` 0 = OK, success, no error (SUCCESS_NO_ERROR) 1 = Cannot open input file (OPEN_ERROR) 2 = Cannot create output file (CREATE_ERROR) 3 = File read error (READ_ERROR) 4 = File write error (WRITE_ERROR) 5 = Not enough memory (MEMORY_ERROR) 6 = Parameter is wrong or missing (BAD_PARAM_ERROR) 7 = Data in wrong format (BAD_FORMAT_ERROR) 8 = Invalid data (INVALID_DATA_ERROR) 9 = Unexpected end of file found (EOF_ERROR) 10 = Required data not found (MISSING_ERROR) 11 = Value out of range (OUT_OF_RANGE_ERROR) 12 = Duplicate data (DUP_ERROR) 13 = Misc file IO error (IO_ERROR) 14 = Unexpected NULL value (NULL_ERROR) 15 = Decryption error (DECRYPT_ERROR) 16 = Item has expired or is not yet valid (EXPIRED_ERROR) 17 = Invalid option (BAD_FLAG_ERROR) 18 = Failed to wipe data (WIPE_ERROR) 19 = Item is not supported (NOT_SUPPORTED_ERROR) 20 = No data found to process (NO_DATA_ERROR) 21 = No match found (NO_MATCH_ERROR) 22 = Signature is invalid (SIGNATURE_ERROR) 23 = Failed a test e.g. known answer test (TEST_FAILED_ERROR) 24 = Key generation failed (KEYGEN_FAILED_ERROR) 25 = Certificate issuer error (ISSUER_ERROR) 26 = Data not a valid length (BAD_LENGTH_ERROR) 27 = Invalid XML format (BAD_XML_ERROR) 29 = Not a valid query (BAD_QUERY_ERROR) 30 = Not enough room in output buffer (SHORT_BUF_ERROR) 31 = Zlib compression error (ZLIB_COMPR_ERROR) 33 = Invalid key length (BAD_KEY_LEN_ERROR) 34 = Invalid block length (BAD_BLK_LEN_ERROR) 35 = Invalid mode (BAD_MODE_ERROR) 36 = Invalid key (BAD_KEY_ERROR) 37 = Invalid initialization vector (BAD_IV_ERROR) 38 = Invalid IV length (BAD_IV_LEN_ERROR) 39 = Unable to encode (ENCODING_ERROR) 42 = Item has been revoked (REVOCATION_ERROR) 43 = Certificate path is invalid (CERT_PATH_ERROR) 201 = PRNG: Cannot open input file (PRNG_ERR_FILE_OPEN) 202 = PRNG: Cannot create output file (PRNG_ERR_FILE_CREATE) 203 = PRNG: File read error (PRNG_ERR_FILE_READ) 204 = PRNG: File write error (PRNG_ERR_FILE_WRITE) 205 = PRNG: File locking error (PRNG_ERR_FILE_LOCK) 210 = PRNG: Uninstantiation failed (PRNG_ERR_UNINST) 211 = PRNG: Requested length is too large (PRNG_ERR_TOOBIG) 212 = PRNG: Function failed (PRNG_ERR_FAILURE) 213 = PRNG: Invalid input parameter (PRNG_ERR_BADPARAM) 214 = PRNG: Function is not available (PRNG_ERR_NOTAVAIL) 299 = PRNG: Catastrophic failure (PRNG_ERR_CATASTROPHIC) 9745 = Something not expected to happen has happened (INTERNAL_ERROR) 9999 = Miscellaneous error (MISC_ERROR) ``` ### Error Handling If an error occurs the function will return one of the above nonzero error codes to indicate the general nature of the problem. This may be a positive or negative value depending on the function. Functions that normally return a positive value to indicate success will return an error code as a negative number. Functions that return zero to indicate success will return a nonzero error code, either positive or negative, depending on obscure historical reasons (to maintain backwards compatibility, sorry). Use the [`PKI_ErrorLookup`](#PKI_ErrorLookup) function or the [General.ErrorLookup](#M_General_ErrorLookup) method to get the corresponding error message for a given error code. If you need to check for a specific error, please use the defined constants (`XXXX_ERROR`) instead of hard-coding the numerical values, which may change in future releases. More than one error may occur during a call to a function. The code returned by a function will reflect the last error that occurred in the chain. Use the [`PKI_ErrorCode`](#PKI_ErrorCode) function or [General.ErrorCode](#M_General_ErrorCode) method to find the code of the first error that occurred. More details on the error can usually be found by using the [`PKI_LastError`](#PKI_LastError) function or [General.LastError](#M_General_LastError) method which contains a description of the error or errors that have occurred. Be warned that not all errors set this description. [[Contents](#topofpage)] [[Index](#index)] Acknowledgements --------------------------------- The source code used in CryptoSys PKI Pro is original code written by David Ireland except for the following: * The DES algorithm includes code by Richard Outerbridge placed in the public domain August 1992. * The AES algorithm includes code placed in the public domain by Vincent Rijmen, Antoon Bosselaers and Paulo Barreto in December 2000. * The SHA-1 algorithm includes code derived from 100% public domain code by Steve Reid with modifications based on work by Peter Gutmann as posted to sci.crypt in message <30ajo5$oe8@ccu2.auckland.ac.nz>. * The code for SHA-3 and its family uses code derived from public domain code by Ronny Van Keer, May 2012, . * The code for RIPEMD-160 is adapted from software written by Antoon Bosselaers [[RMD](#RMD)]. * The HMAC algorithm includes code from RFC 2104 *HMAC: Keyed-Hashing for Message Authentication* [[HMAC](#HMAC)]. * The code to read and write ASN.1 files uses techniques from the `DUMPASN1.C` program by Peter Gutmann . * The ZLIB data compression utilities use source code with permission from the *'zlib' general purpose compression library* version 1.2.3 Copyright (C) 1995-2005 Jean-loup Gailly and Mark Adler. * The code for curve25519 uses code under an MIT license by Mehdi Sotoodeh . * The code for curve448 is based on code by Mike Hamburg under an MIT license . * The code for Salsa20 and ChaCha20 uses code derived from public domain code by D.J. Bernstein, . * The code for Poly1305 uses code adapted from public domain software by Andrew Moon, . * Multiple-precision arithmetic is carried out using a modified version of the `BIGDIGITS` library first published June 2001 by David Ireland <[https://www.di-mgt.com.au/bigdigits.html](https://www.di-mgt.com.au/bigdigits.html "External link")>. * The code to prompt for keyboard entropy and wipe files is derived from code published in *Secure Programming Cookbook* [[VIEG03](#VIEG03)]. * The code to process JSON uses source code 'json.c' Copyright (C) 2011 Joseph A. Adams (joeyadams3.14159@gmail.com). * The code to call Intel DRNG functions uses source code Copyright (C) 2014, Intel Corporation with [conditions](https://cryptosys.net/docs/intel_drng_license.txt "External link"). * Some code to produce incidental pseudorandom numbers (*not* the core secure Random Number Generator) uses source code from "TinyMT32 Pseudo Random Number Generator (PRNG)" Copyright (c) 2011, 2013 Mutsuo Saito, Makoto Matsumoto, Hiroshima University and The University of Tokyo under a BSD-3-Clause [license](https://github.com/MersenneTwister-Lab/TinyMT/blob/master/LICENSE.txt "External link"). * The MD5 algorithm includes code derived from the *RSA Data Security, Inc. MD5 Message-Digest Algorithm* [[RFC1321](#RFC1321)] which is covered by the following licence: > Copyright (C) 1991-2, RSA Data Security, Inc. Created 1991. All rights reserved. > License to copy and use this software is granted provided that it is identified as the > ``RSA Data Security, Inc. MD5 Message-Digest Algorithm'' in all material mentioning or > referencing this software or this function. > License is also granted to make and use derivative works provided that such works are > identified as ``derived from the RSA Data Security, Inc. MD5 Message-Digest Algorithm'' > in all material mentioning or referencing the derived work. > RSA Data Security, Inc. makes no representations concerning either the merchantability > of this software or the suitability of this software for any particular purpose. > It is provided ``as is'' without express or implied warranty of any kind. > These notices must be retained in any copies of any part of this documentation and/or software. * Ditto for MD2, the "RSA Data Security, Inc. MD2 Message Digest Algorithm" [[RFC1319](#RFC1319)]. Thanks to the guys at [NullSoft](http://nsis.sourceforge.net/Main_Page "External link") for their Nullsoft Scriptable Install System. *[New in v20.5]* We are most grateful to Daniel Gillmor for the latest *S/MIME Example Keys and Certificates* in RFC9216 [[SMIME-LAMPS](#SMIME-LAMPS)]. [[Contents](#topofpage)] [[Index](#index)] Primary References ----------------------------------------- These are the primary references we used to create CryptoSys PKI Pro. * **[CMS]** [RFC 5652](https://tools.ietf.org/html/rfc5652 "External link"), *Cryptographic Message Syntax (CMS)*, R. Housley, September 2009 (obsoletes RFC3852, RFC3369, RFC2630). * **[CMSALG]** [RFC 3370](https://tools.ietf.org/html/rfc3370 "External link"), *Cryptographic Message Syntax (CMS) Algorithms*, R. Housley, August 2002. * **[FIPS180]** Federal Information Processing Standard, FIPS PUB 180-4 *Secure Hash Standard (SHS)*, U.S. Department of Commerce/National Institute of Standards and Technology, August 2015. ([NIST.FIPS.180-4](https://doi.org/10.6028/NIST.FIPS.180-4 "External link")). * **[FIPS197]** Federal Information Processing Standard, FIPS PUB 197 *Advanced Encryption Standard (AES)*, U.S. Department of Commerce/National Institute of Standards and Technology, 26 November 2001, Updated May 9, 2023. ([NIST.FIPS.197](https://doi.org/10.6028/NIST.FIPS.197-upd1 "External link")). * **[FIPS198]** Federal Information Processing Standard, FIPS PUB 198-1 *The Keyed-Hash Message Authentication Code (HMAC)*, U.S. Department of Commerce/National Institute of Standards and Technology, July 2008. ([NIST.FIPS.198-1](https://doi.org/10.6028/NIST.FIPS.198-1 "External link")). * **[FIPS202]** Federal Information Processing Standard, FIPS PUB 202 *SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions*, U.S. Department of Commerce/National Institute of Standards and Technology, August 2015. ([NIST.FIPS.202](https://doi.org/10.6028/NIST.FIPS.202 "External link")). * **[JWK]** [RFC 7517](https://tools.ietf.org/html/rfc7517 "External link"), *JSON Web Key (JWK)*, M. Jones, May 2015. * **[PKCS1]** PKCS #1, *RSA Cryptography Standard*, RSA Laboratories, Version 2.2, October 2012 (republished as [[RFC8017](#RFC8017)]). * **[PKCS5]** PKCS #5, *Password-Based Encryption Standard*, RSA Laboratories, Version 2.2, October 2012 (republished as [[RFC8018](#RFC8018)]). * **[PKCS8]** PKCS #8, *Private-Key Information Syntax Standard*, RSA Laboratories, Version 1.2, Nov 1993 (republished as [[RFC5208](#RFC5208)] and [[RFC5958](#RFC5958)]) * **[PKCS10]** PKCS #10, *Certification Request Syntax Standard*, RSA Laboratories, Version 1.7, May 2000 (republished as [[RFC2986](#RFC2986) plus [[RFC5967](#RFC5967)]). * **[PKCS12]** PKCS #12, *Personal Information Exchange Syntax*, RSA Laboratories, Version 1.1, October 2012 (republished as [[RFC7292](#RFC7292)]). * **[PKCS-EX]** Burton S Kaliski, Jr, *Some Examples of the PKCS Standards*, RSA Laboratories Technical Note, Nov 1993. * **[PKIX]** [RFC 5280](https://tools.ietf.org/html/rfc5280 "External link"), *Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile*, R. Housley et al, May 2008 * **[PKIXALG]** [RFC 3279](https://tools.ietf.org/html/rfc3279 "External link"), *Algorithms and Identifiers for the Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile*, R. Housley et al, April 2002 * **[RFC3274]** [RFC 3274](https://tools.ietf.org/html/rfc3274 "External link"), *Compressed Data Content Type for Cryptographic Message Syntax (CMS)*, P. Gutmann, June 2002. * **[RFC3565]** [RFC 3565](https://tools.ietf.org/html/rfc3565 "External link"), *Use of the Advanced Encryption Standard (AES) Encryption Algorithm in Cryptographic Message Syntax (CMS)*, J. Schaad, July 2003. * **[RFC4056]** [RFC 4056](https://tools.ietf.org/html/rfc4056 "External link"), *Use of the RSASSA-PSS Signature Algorithm in Cryptographic Message Syntax (CMS)*. J. Schaad. June 2005. * **[RFC5116]** [RFC 5116](https://tools.ietf.org/html/rfc5116 "External link"), *An Interface and Algorithms for Authenticated Encryption*. D. McGrew. January 2008. * []()**[RFC5639]** [RFC 5639](https://tools.ietf.org/html/rfc5639 "External link") *Elliptic Curve Cryptography (ECC) Brainpool Standard Curves and Curve Generation*. M. Lochter, J. Merkle. March 2010. * **[RFC6090]** [RFC 6090](https://tools.ietf.org/html/rfc6090 "External link"), *Fundamental Elliptic Curve Cryptography Algorithms*, McGrew, D., Igoe, K., M. Salter, February 2011 (and RFC Errata, [Erratum ID 3920](https://www.rfc-editor.org/errata_search.php?rfc=6090 "External link")). * **[RFC6960]** [RFC 6960](https://tools.ietf.org/html/rfc6960 "External link"), *X.509 Internet Public Key Infrastructure Online Certificate Status Protocol - OCSP*, M. Myers, et al, June 2013. * **[RFC6979]** [RFC 6979](https://tools.ietf.org/html/rfc6979 "External link") *Deterministic Usage of the Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (ECDSA)*. T. Pornin. August 2013. * **[RFC7748]** [RFC 7748](https://tools.ietf.org/html/rfc7748 "External link") *Elliptic Curves for Security*. A. Langley, M. Hamburg, S. Turner. January 2016. * **[RFC7914]** [RFC 7914](https://tools.ietf.org/html/rfc7914 "External link") *The scrypt Password-Based Key Derivation Function*. C. Percival, S. Josefsson. 2016. * **[RFC8032]** [RFC 8032](https://tools.ietf.org/html/rfc8032 "External link") *Edwards-Curve Digital Signature Algorithm (EdDSA)*. S. Josefsson, I. Liusvaara. January 2017. * **[RFC8103]** [RFC 8103](https://tools.ietf.org/html/rfc8103 "External link") *Using ChaCha20-Poly1305 Authenticated Encryption in the Cryptographic Message Syntax (CMS)*. R. Housley. February 2017. * **[RFC8439]** [RFC 8439](https://tools.ietf.org/html/rfc8439 "External link") *ChaCha20 and Poly1305 for IETF Protocols*. Y. Nir, A. Langley. June 2018. (Obsoletes RFC7539) * **[SMIME-EX]** [RFC 4134](https://tools.ietf.org/html/rfc4134 "External link"), *Examples of S/MIME Messages*, P. Hoffman (ed), July 2005. * **[SMIME-LAMPS]** [RFC 9216](https://tools.ietf.org/html/rfc9216 "External link") *S/MIME Example Keys and Certificates*. D.K. Gillmor, Ed., April 2022. * **[SMIME-MSG]** [RFC 5751](https://tools.ietf.org/html/rfc5751 "External link"), *Secure/Multipurpose Internet Mail Extensions (S/MIME) Version 3.2 Message Specification*, B. Ramsdell, S. Turner, January 2010 (obsoletes RFC2633, RFC3851). * **[SP80090A]** NIST Special Publication 800-90A, *Recommendation for Random Number Generation Using Deterministic Random Bit Generators*, Elaine Barker and John Kelsey, National Institute of Standards and Technology, June 2015. [NIST.SP.800-90Ar1](http://dx.doi.org/10.6028/NIST.SP.800-90Ar1 "External link"). [[Contents](#topofpage)] [[Index](#index)] Bibliography ------------------------------------- Other works we referred to in creating CryptoSys PKI Pro. * **[AES-WRAP]** *AES Key Wrap Specification*, National Institute of Standards and Technology, 16 November 2001. Superseded by [[SP800-38F](#SP800-38F)]. * **[BALE05]** Francesco Balena and Giuseppe Dimauro, *Practical Guidelines and Best Practices for Microsoft Visual Basic and Visual C# Developers*, Microsoft Press, 2005, ISBN 0735621721. * **[BTC-B58]** Bitcoin Wiki, *Base58Check encoding*, , (accessed January 2016). * **[BROW99]** Steve Brown, *Visual Basic Developer's Guide to the Win32 API*, Sybex, 1999. * **[CADES]** ETSI TS 103 173: Electronic Signatures and Infrastructures (ESI) *CAdES Baseline Profile*, V2.1.1 (2012-03), March 2012, . * **[CHAN]** Mahesh Chand, *Tutorial: Creating C# Class Library (DLL) Using Visual Studio .NET*, (accessed July 2006). * **[COHE99]** Aaron Cohen and Mike Woodring, *Win32 Multithreaded Programming*, O'Rielly, 1999. * **[CURVE25519]** Daniel J. Bernstein. *A state-of-the-art Diffie-Hellman function*. <[http://cr.yp.to/ecdh.html](http://cr.yp.to/ecdh.html "External link")>, accessed 13 September 2020. * **[DEVIL]** Scott Berinato, *The Devil's Infosec Dictionary*, , (accessed July 2010). * **[DOWD06]** Mark Dowd, John McDonald and Justin Schuh, *The Art of Software Security Assessment*, Addison-Wesley, 2006. * **[DUBU00]** Olivier Dubuisson, *ASN.1 Communication between Heterogeneous Systems*, , June 2000. * **[DRBGVS]** Timothy A. Hall, *The NIST SP 800-90A Deterministic Random Bit Generator Validation System (DRBGVS)*, National Institute of Standards and Technology, Updated 29 October 2015, [DRBGVS.pdf](https://csrc.nist.gov/CSRC/media/Projects/Cryptographic-Algorithm-Validation-Program/documents/drbg/DRBGVS.pdf "External link") * **[ED25519]** Daniel J. Bernstein, Niels Duif, Tanja Lange, Peter Schwabe, Bo-Yin Yang. *Ed25519: high-speed high-security signatures*. <[http://ed25519.cr.yp.to/](http://ed25519.cr.yp.to/ "External link")>, version 2017.01.22. * **[EDIFACT]** UN/EDIFACT Finance Group D6 SWG-F, *Recommended Practice For Message Flow And Security For Edifact Payments*, Version 2v03, 1 October 2000, , (accessed January 2009). * **[FERG03]** Niels Ferguson and Bruce Schneier, *Practical Cryptography*, John Wiley, 2003. * **[FERG10]** Niels Ferguson, Bruce Schneier and Tadayoshi Kohno, *Cryptography Engineering*, John Wiley, 2010. * **[FIPS140]** Federal Information Processing Standards Publication FIPS PUB 140-2 *Security Requirements for Cryptographic Modules*, U.S. Department Of Commerce/National Institute of Standards and Technology, 25 May 2001, Change Notice 1 (10 October 2001) and Change Notice 2 (3 December 2002). * **[FIPS140IG]** *Implementation Guidance for FIPS PUB 140-1 and the Cryptographic Module Validation Program*, U.S. Department Of Commerce/National Institute of Standards and Technology, update 10 January 2002. * **[FIPS140XC]** Federal Information Processing Standards Publication FIPS PUB 140-2 *Annex C: Approved Random Number Generators for FIPS PUB 140-2*, U.S. Department Of Commerce/National Institute of Standards and Technology, draft, 24 January 2007. * **[FIPS186]** Federal Information Processing Standard, FIPS PUB 186-4 *Digital Signature Standard (DSS)*, U.S. Department of Commerce/National Institute of Standards and Technology, July 2013. * **[GOLDILOCKS]** Mike Hamburg. *Ed448-Goldilocks, a new elliptic curve*. <[http://eprint.iacr.org/2015/625.pdf](http://eprint.iacr.org/2015/625.pdf "External link")>, 2015. * **[GUTPFX]** Peter Gutmann, *PFX - How Not to Design a Crypto Protocol/Standard*, , (last accessed January 2007). * **[GUTX509]** Peter Gutmann, *X.509 Style Guide*, , Oct 2000. * **[HANS97]** David R. Hanson, *C Interfaces and Implementations*, Addison-Wesley, 1997. * **[HMAC]** [RFC 2104](https://tools.ietf.org/html/rfc2104 "External link") *HMAC: Keyed-Hashing for Message Authentication*, Krawczyk, Bellare and Canetti, February 1997. * **[HOWA02]** Michael Howard and David LeBlanc, *Writing Secure Code*, Microsoft Press, 2002. * **[IEEE1363]** Institute for Electrical and Electronics Engineers (IEEE) Standard 1363-2000, *Standard Specifications for Public Key Cryptography*, January 2000. * **[INTEL-DRNG]** Intel Corporation, *Intel Digital Random Number Generator (DRNG) Software Implmentation Guide*, ID 658356, Revision 2.1, October 17, 2018 ([link](https://www.intel.com/content/www/us/en/developer/articles/guide/intel-digital-random-number-generator-drng-software-implementation-guide.html "External link") accessed December 2023). * **[ISO18033-2]** ISO/IEC 18033-2:2006, *Information technology - Security techniques - Encryption algorithms - Part 2: Asymmetric ciphers*, Ed. Victor Shoup, 2006. The final committee draft version *FCD 18033-2*, dated December 2004, is available at . * **[ISO8601]** ISO 8601:1988(E), *Data elements and interchange formats - Information interchange - Representation of dates and times*, 1988 (actually we just cribbed this reference from W3C's *Date and Time Formats*, , Misha Wolf and Charles Wicksteed, Sept 1997). * **[JWA]** [RFC 7518](https://tools.ietf.org/html/rfc7518 "External link"), *JSON Web Algorithms (JWA)*, M. Jones, May 2015. * **[JWS]** [RFC 7515](https://tools.ietf.org/html/rfc7515 "External link"), *JSON Web Signature (JWS)*, M. Jones et al, May 2015. * **[KALI-ASN]** Burton S Kaliski, Jr, *A Layman's Guide to a Subset of ASN.1, BER and DER*, RSA Laboratories Technical Note, Nov 1993. * **[KELS98]** John Kelsey, Bruce Schneier, David Wagner, Chris Hall, *Cryptanalytic Attacks on Pseudorandom Number Generators*, March 1998, available from . * **[KUHN]** Markus Kuhn, *UTF-8 and Unicode FAQ for Unix/Linux*, , (accessed August 2006). * **[LARM99]** Prof John Larmouth, *ASN.1 Complete*, , Open Systems Solutions, 1999. * **[MENE97]** Menezes, van Oorschot and Vanstone, *Handbook of Applied Cryptography*, CRC Press LLC, 1997. * **[NIST-MATH]** USG National Security Agency, *Mathematical routines for the NIST prime elliptic curves*, April 2010, (accessed October 2015). * **[NISPOM]** DOD 5220.22-M, *National Industry Security Program Operating Manual (NISPOM)*, US Department of Defense, January 1995. * **[SIEM99]** Siemens Financial Services, *Electronic Signing of PAYMUL Messages*, autack.doc, April 1999, (accessed January 2009). * **[PETZ99]** Charles Petzold, *Programming Windows*, 5th edition, Microsoft Press, 1999. * **[PKCS7]** PKCS #7, *Cryptographic Message Syntax Standard*, RSA Laboratories, Version 1.5, Nov 1993 (also [[RFC2315](#RFC2315)]). * **[PKCS7-EXT]** RSA Laboratories Technical Note, *Extensions and Revisions to PKCS #7*, Burton S. Kaliski Jr. and Kevin W. Kingdon, May 1997. * **[PKIX-MAP]** Internet Draft, *PKIX Roadmap*, IETF-PKIX Working Group, , July 2002. * **[RICH99]** Jeffrey Richter, *Programming Applications for Microsoft Windows*, 4th edition, Microsoft Press, 1999. * **[RFC1319]** [RFC 1319](https://tools.ietf.org/html/rfc1319 "External link"), *The MD2 Message-Digest Algorithm*, B. Kaliski, RSA Data Security, Inc., April 1992. * **[RFC1321]** [RFC 1321](https://tools.ietf.org/html/rfc1321 "External link"), *The MD5 Message-Digest Algorithm*, R. Rivest, RSA Data Security, Inc., April 1992. * **[RFC1421]** [RFC 1421](https://tools.ietf.org/html/rfc1421 "External link"), *Privacy Enhancement for Internet Electronic Mail*, J. Linn, February 1993. * **[RFC1423]** [RFC 1423](https://tools.ietf.org/html/rfc1423 "External link"), *Privacy Enhancement for Internet Electronic Mail: Part III: Algorithms, Modes, and Identifiers*, D. Balenson, February 1993. * **[RFC1924]** [RFC 1924](https://tools.ietf.org/html/rfc1924 "External link"), *A Compact Representation of IPv6 Addresses*, R. Elz, April 1 1996. * **[RFC2202]** [RFC 2202](https://tools.ietf.org/html/rfc2202 "External link"), *Test Cases for HMAC-MD5 and HMAC-SHA-1*, P. Cheng and R. Glenn, September 1997. * **[RFC2279]** [RFC 2279](https://tools.ietf.org/html/rfc2279 "External link"), *UTF-8, a transformation format of ISO 10646*, F. Yergeau, January 1998. * **[RFC2315]** [RFC 2315](https://tools.ietf.org/html/rfc2315 "External link"), *PKCS #7: Cryptographic Message Syntax Version 1.5*, B. Kaliski, March 1998. * **[RFC2634]** [RFC 2634](https://tools.ietf.org/html/rfc2634 "External link") *Enhanced Security Services for S/MIME*. P. Hoffman. June 1999. * **[RFC2986]** [RFC 2986](https://tools.ietf.org/html/rfc2986 "External link") *PKCS #10: Certification Request Syntax Specification Version 1.7*. M. Nystrom, B. Kaliski. November 2000. * **[RFC2898]** [RFC 2898](https://tools.ietf.org/html/rfc2898 "External link"), *PKCS #5: Password-Based Cryptography Specification Version 2.0*, B. Kaliski, September 2000. * **[RFC3211]** [RFC 3211](https://tools.ietf.org/html/rfc3211 "External link"), *Password-based Encryption for CMS*, P. Gutmann, December 2001. * **[RFC3217]** [RFC 3217](https://tools.ietf.org/html/rfc3217 "External link"), *Triple-DES and RC2 Key Wrapping*, R. Housley, December 2001. * **[RFC3275]** [RFC 3275](https://tools.ietf.org/html/rfc3275 "External link"), *XML-Signature Syntax and Processing*, D. Eastlake et al, March 2002. * **[RFC3279]** [RFC 3279](https://tools.ietf.org/html/rfc3279 "External link") *Algorithms and Identifiers for the Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile*. L. Bassham, W. Polk, R. Housley. April 2002. * **[RFC3394]** [RFC 3394](https://tools.ietf.org/html/rfc3394 "External link"), *Advanced Encryption Standard (AES) Key Wrap Algorithm*, J. Schaad and R. Housley, September 2002. * **[RFC3447]** [RFC 3447](https://tools.ietf.org/html/rfc3447 "External link") *Public-Key Cryptography Standards (PKCS) #1: RSA Cryptography Specifications Version 2.1*. J. Jonsson, B. Kaliski. February 2003. * **[RFC3537]** [RFC 3537](https://tools.ietf.org/html/rfc3537 "External link"), *HMAC Key Wrap*, J. Schaad and R. Housley, May 2003. * **[RFC3560]** [RFC 3560](https://tools.ietf.org/html/rfc3560 "External link"), *Use of the RSAES-OAEP Key Transport Algorithm in the Cryptographic Message Syntax (CMS)*, R. Housley, July 2003. * **[RFC4050]** [RFC 4050](https://tools.ietf.org/html/rfc4050 "External link"), *Using the Elliptic Curve Signature Algorithm (ECDSA) for XML Digital Signatures*, S. Blake-Wilson et al, April 2005. * **[RFC4055]** [RFC 4055](https://tools.ietf.org/html/rfc4055 "External link"), *Additional Algorithms and Identifiers for RSA Cryptography for use in the Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile*. J. Schaad, B. Kaliski, R. Housley. June 2005. * **[RFC4086]** [RFC 4086](https://tools.ietf.org/html/rfc4086 "External link"), *Randomness Requirements for Security*, D. Eastlake et al, June 2005. * **[RFC4122]** [RFC 4122](https://tools.ietf.org/html/rfc4122 "External link"), *A Universally Unique IDentifier (UUID) URN Namespace*, Leach, P. and Mealling, M. and Salz, R., July 2005. * **[RFC4231]** [RFC 4231](https://tools.ietf.org/html/rfc4231 "External link"), *Identifiers and Test Vectors for HMAC-SHA-224, HMAC-SHA-256, HMAC-SHA-384, and HMAC-SHA-512*, M. Nystrom, December 2005. * **[RFC4262]** [RFC 4262](https://tools.ietf.org/html/rfc4262 "External link") *X.509 Certificate Extension for Secure/Multipurpose Internet Mail Extensions (S/MIME) Capabilities*. S. Santesson. December 2005. * **[RFC4514]** [RFC 4514](https://tools.ietf.org/html/rfc4514 "External link"), *Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names*, K. Zeilenga, Ed., OpenLDAP Foundation, June 2006. * **[RFC4519]** [RFC 4519](https://tools.ietf.org/html/rfc4519 "External link"), *Lightweight Directory Access Protocol (LDAP): Schema for User Applications*, A. Sciberras, Ed., June 2006. * **[RFC4648]** [RFC 4648](https://tools.ietf.org/html/rfc4648 "External link"), *The Base16, Base32, and Base64 Data Encodings*, S. Josefsson, October 2006. * **[RFC4754]** [RFC 4754](https://tools.ietf.org/html/rfc4754 "External link") *IKE and IKEv2 Authentication Using the Elliptic Curve Digital Signature Algorithm (ECDSA)*. D. Fu, J. Solinas. January 2007. * **[RFC5035]** [RFC 5035](https://tools.ietf.org/html/rfc5035 "External link") *Enhanced Security Services (ESS) Update: Adding CertID Algorithm Agility*. J. Schaad. August 2007. * **[RFC5083]** [RFC 5083](https://tools.ietf.org/html/rfc5083 "External link") *Cryptographic Message Syntax (CMS) Authenticated-Enveloped-Data Content Type*. R. Housley. November 2007. * **[RFC5084]** [RFC 5084](https://tools.ietf.org/html/rfc5084 "External link") *Using AES-CCM and AES-GCM Authenticated Encryption in the Cryptographic Message Syntax (CMS)*. R. Housley. November 2007. * **[RFC5208]** [RFC 5208](https://tools.ietf.org/html/rfc5208 "External link") *Public-Key Cryptography Standards (PKCS) #8: Private-Key Information Syntax Specification Version 1.2*. B. Kaliski. May 2008 (Obsoleted by [[RFC5958](#RFC5958)]). * **[RFC5280]** [RFC 5280](https://tools.ietf.org/html/rfc5280 "External link") *Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile*. D. Cooper, S. Santesson, S. Farrell, S. Boeyen, R. Housley, W. Polk. May 2008. * **[RFC5349]** [RFC 5349](https://tools.ietf.org/html/rfc5349 "External link") *Elliptic Curve Cryptography (ECC) Support for Public Key Cryptography for Initial Authentication in Kerberos (PKINIT)*. L. Zhu, K. Jaganathan, K. Lauter. September 2008. * **[RFC5480]** [RFC 5480](https://tools.ietf.org/html/rfc5480 "External link") *Elliptic Curve Cryptography Subject Public Key Information*. S. Turner, D. Brown, K. Yiu, R. Housley, T. Polk. March 2009. * **[RFC5652]** [RFC 5652](https://tools.ietf.org/html/rfc5652 "External link") *Cryptographic Message Syntax (CMS)*. R. Housley. September 2009. * **[RFC5750]** [RFC 5750](https://tools.ietf.org/html/rfc5750 "External link"), *Secure/Multipurpose Internet Mail Extensions (S/MIME) Version 3.2 Certificate Handling*, B. Ramsdell, January 2010 (Obsoletes RFC3850). * **[RFC5753]** [RFC 5753](https://tools.ietf.org/html/rfc5753 "External link") *Use of Elliptic Curve Cryptography (ECC) Algorithms in Cryptographic Message Syntax (CMS)*. S. Turner, D. Brown. January 2010. * **[RFC5754]** [RFC 5754](https://tools.ietf.org/html/rfc5754 "External link"), *Using SHA2 Algorithms with Cryptographic Message Syntax*, S. Turner, January 2010 (Updates RFC3370). * **[RFC5756]** [RFC 5756](https://tools.ietf.org/html/rfc5756 "External link") *Updates for RSAES-OAEP and RSASSA-PSS Algorithm Parameters*. S. Turner, D. Brown, K. Yiu, R. Housley, T. Polk. January 2010. * **[RFC5869]** [RFC 5869](https://tools.ietf.org/html/rfc5869 "External link") *HMAC-based Extract-and-Expand Key Derivation Function (HKDF)*. H. Krawczyk, P. Eronen. May 2010. * **[RFC5911]** [RFC 5911](https://tools.ietf.org/html/rfc5911 "External link") *New ASN.1 Modules for Cryptographic Message Syntax (CMS) and S/MIME*. P. Hoffman, J. Schaad. June 2010. * **[RFC5912]** [RFC 5912](https://tools.ietf.org/html/rfc5912 "External link") *New ASN.1 Modules for the Public Key Infrastructure Using X.509 (PKIX)*. P. Hoffman, J. Schaad. June 2010. * **[RFC5915]** [RFC 5915](https://tools.ietf.org/html/rfc5915 "External link") *Elliptic Curve Private Key Structure*. S. Turner, D. Brown. June 2010. * **[RFC5958]** [RFC 5958](https://tools.ietf.org/html/rfc5958 "External link") *Asymmetric Key Packages*. S. Turner. August 2010. * **[RFC5967]** [RFC 5967](https://tools.ietf.org/html/rfc5967 "External link") *The application/pkcs10 Media Type*. S. Turner. August 2010. * **[RFC5990]** [RFC 5990](https://datatracker.ietf.org/doc/html/rfc5990 "External link") *Use of the RSA-KEM Key Transport Algorithm in the Cryptographic Message Syntax (CMS)*. J. Randall, B. Kaliski, J. Brainard, S. Turner. September 2010. * **[RFC5990bis]** [RFC 5990bis](https://datatracker.ietf.org/doc/draft-ietf-lamps-rfc5990bis/ "External link") *Use of the RSA-KEM Algorithm in the Cryptographic Message Syntax (CMS) draft-ietf-lamps-rfc5990bis-10*. R. Housley, S. Turner. July 2024. * **[RFC6025]** [RFC 6025](https://tools.ietf.org/html/rfc6025 "External link") *ASN.1 Translation*. C. Wallace, C. Gardiner. October 2010. * **[RFC6211]** [RFC 6211](https://tools.ietf.org/html/rfc6211 "External link") *Cryptographic Message Syntax (CMS) Algorithm Identifier Protection Attribute*. J. Schaad. April 2011. * **[RFC6268]** [RFC 6268](https://tools.ietf.org/html/rfc6268 "External link") *Additional New ASN.1 Modules for the Cryptographic Message Syntax (CMS) and the Public Key Infrastructure Using X.509 (PKIX)*. J. Schaad, S. Turner. July 2011. * []()**[RFC7027]** [RFC 7027](https://tools.ietf.org/html/rfc7027 "External link") *Elliptic Curve Cryptography (ECC) Brainpool Curves for Transport Layer Security (TLS)*. J. Merkle, M. Lochter. October 2013. * **[RFC7292]** [RFC 7292](https://tools.ietf.org/html/rfc7292 "External link") *PKCS #12: Personal Information Exchange Syntax v1.1*. K. Moriarty, Ed., M. Nystrom, S. Parkinson, A. Rusch, M. Scott. July 2014. * **[RFC7468]** [RFC 7468](https://tools.ietf.org/html/rfc7468 "External link") *Textual Encodings of PKIX, PKCS, and CMS Structures*, S. Josefsson, S. Leonard. April 2015. * **[RFC7515]** [RFC 7515](https://tools.ietf.org/html/rfc7515 "External link") *JSON Web Signature (JWS)*. M. Jones, J. Bradley, N. Sakimura. May 2015. * **[RFC8017]** [RFC 8017](https://tools.ietf.org/html/rfc8017 "External link") *PKCS #1: RSA Cryptography Specifications Version 2.2*. K. Moriarty, Ed., B. Kaliski, J. Jonsson, A. Rusch. November 2016. * **[RFC8018]** [RFC 8018](https://tools.ietf.org/html/rfc8018 "External link") *PKCS #5: Password-Based Cryptography Specification Version 2.1*. K. Moriarty, Ed., B. Kaliski, A. Rusch. January 2017. * **[RFC8410]** [RFC 8410](https://tools.ietf.org/html/rfc8410 "External link") *Algorithm Identifiers for Ed25519, Ed448, X25519, and X448 for Use in the Internet X.509 Public Key Infrastructure*. S. Josefsson, J. Schaad. August 2018. * **[RFC8418]** [RFC 8418](https://tools.ietf.org/html/rfc8418 "External link") *Use of the Elliptic Curve Diffie-Hellman Key Agreement Algorithm with X25519 and X448 in the Cryptographic Message Syntax (CMS)*. R. Housley. August 2018. * **[RFC8419]** [RFC 8419](https://tools.ietf.org/html/rfc8419 "External link") *Use of Edwards-Curve Digital Signature Algorithm (EdDSA) Signatures in the Cryptographic Message Syntax (CMS)*. R. Housley. August 2018. * **[RFC8619]** [RFC 8619](https://datatracker.ietf.org/doc/html/rfc8619 "External link") *Algorithm Identifiers for the HMAC-based Extract-and-Expand Key Derivation Function (HKDF)*. R. Housley. June 2019. * **[RFC8933]** [RFC 8933](https://tools.ietf.org/html/rfc8933 "External link") *Update to the Cryptographic Message Syntax (CMS) for Algorithm Identifier Protection*. R. Housley. October 2020. * **[RFC9180]** [RFC 9180](https://tools.ietf.org/html/rfc9180 "External link") *Hybrid Public Key Encryption*. R. Barnes, et al. February 2022. * **[RFC9629]** [RFC 9629](https://datatracker.ietf.org/doc/html/rfc9629 "External link") *Using Key Encapsulation Mechanism (KEM) Algorithms in the Cryptographic Message Syntax (CMS)*. R. Housley, J. Gray, T. Okubo. August 2024. * **[RMD]** Antoon Bosselaers, *The RIPEMD-160 Page*, , last updated 25 August 2004. * **[SAFECURVES]** Daniel J. Bernstein and Tanja Lange. *SafeCurves: choosing safe curves for elliptic-curve cryptography*. [https://safecurves.cr.yp.to/](https://safecurves.cr.yp.to/ "External link"), version 2017.01.22. * **[SCHN96]** Bruce Schneier, *Applied Cryptography - Protocols, Algorithms and Source Code in C*, 2nd edition, John Wiley, 1996. * **[SEAC05]** Robert C. Seacord, *Secure Coding in C and C++*, Addison-Wesley, 2005. * **[SEC1]** Certicom Research. Standards for Efficient Cryptography, *SEC 1: Elliptic Curve Cryptography*, version 2.0, May 2009, . * **[SIMO97]** Richard J Simon, *Windows NT Win32 API SuperBible*, Waite Group Press, 1997. * **[SP800-20]** NIST Special Publication 800-20, *Modes of Operation Validation System for the Triple Data Encryption Algorithm (TMOVS): Requirements and Procedures*, National Institute of Standards and Technology, April 2000. * **[SP800-38A]** NIST Special Publication 800-38A, *Recommendation for Block Cipher Modes of Operation*, National Institute of Standards and Technology, December 2001. * **[SP800-38D]** NIST Special Publication 800-38D, *Recommendation for Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC*, National Institute of Standards and Technology, November 2007. * **[SP800-38F]** NIST Special Publication 800-38F, *Recommendation for Block Cipher Modes of Operation: Methods for Key Wrapping*, National Institute of Standards and Technology, December 2012. * **[SP800-56A]** NIST Special Publication 800-56A, *Recommendation for Pair-Wise Key-Establishment Schemes Using Discrete Logarithm Cryptography*, National Institute of Standards and Technology, Revision 3, April 2018. * **[SP800-57]** NIST Special Publication 800-57, *Recommendation for Key Management - Part 1: General*, National Institute of Standards and Technology, Revision 5, May 2020. * **[SP800-67]** NIST Special Publication 800-67, *Recommendation for the Triple Data Encryption Algorithm (TDEA) Block Cipher*, National Institute of Standards and Technology, Version 1.1, Revised May 2008. * **[SP800-185]** NIST Special Publication 800-185, *SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash and ParallelHash*, John Kelsey, Shu-jen Chang, Ray Perlner, National Institute of Standards and Technology, December 2016. [NIST.SP.800-185.pdf](https://doi.org/10.6028/NIST.SP.800-185 "External link"). * **[SPHINCS]** *SPHINCS+ Submission to the NIST post-quantum project, v.3.1*. Andreas Hülsing et al. [sphincs+-r3.1-specification.pdf](https://sphincs.org/data/sphincs+-r3.1-specification.pdf "External link"), 10 June 2022. * **[STAL]** William Stallings, *Cryptography and Network Security: Principles and Practice*, 4th edition, Prentice Hall, 2006. * **[VIEG02]** John Viega and Gary McGraw, *Building Secure Software*, Addison-Wesley, 2002. * **[VIEG03]** John Viega and Matt Messier, *Secure Programming Cookbook for C and C++*, O'Reilly, 2003. * **[X-208]** International Telecommunication Union, *Specification of Abstract Syntax Notation One (ASN.1)*, CCITT Recommendation X.208, 1988. * **[X-209]** International Telecommunication Union, *Specification of Basic Encoding Rules for Abstract Syntax Notation One (ASN.1)*, CCITT Recommendation X.209, 1988. * **[X-690]** International Telecommunication Union, *ASN.1 encoding rules: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER)*, CCITT Recommendation X.690, July 2002. * **[X9-23]** ANSI X9.23-1998, American National Standard X9.23, *Financial Institution Encryption of Wholesale Financial Messages*, American National Standards Institute, 1998. * **[X9-31]** ANSI X9.31-1998, American National Standard X9.31, *Digital Signatures using Reversible Public Key Cryptography for the Financial Services Industry (rDSA)*, Appendix A, American National Standards Institute, 1998. * **[X9-44]** ANSI X9.44-2007, American National Standard X9.44, *Public Key Cryptography for the Financial Services Industry - Key Establishment Using Integer Factorization Cryptography*, American National Standards Institute, 1998. * **[X9-62]** ANSI X9.62-1998, American National Standard X9.62, *Public Key Cryptography For The Financial Services Industry: The Elliptic Curve Digital Signature Algorithm (ECDSA)*, American National Standards Institute, 1998. * **[X9-63]** ANSI X9.63-2001, American National Standard X9.63, *Public Key Cryptography For The Financial Services Industry: Key Agreement and Key Transport Using Elliptic Curve Cryptography*, American National Standards Institute, November 2001. * **[XKMS]** W3C Recommendation, *XML Key Management Specification (XKMS 2.0)*, [https://www.w3.org/TR/xkms2/](https://www.w3.org/TR/xkms2/ "External link"), 28 June 2005. * **[XMLDSIG]** W3C Recommendation, *XML-Signature Syntax and Processing*, [https://www.w3.org/TR/xmldsig-core/](https://www.w3.org/TR/xmldsig-core/ "External link"), 12 February 2002. * **[XMLENC]** W3C Recommendation, *XML Encryption Syntax and Processing Version 1.1*, [https://www.w3.org/TR/xmlenc-core1/](https://www.w3.org/TR/xmlenc-core1/ "External link"), 11 April 2013. [[Contents](#topofpage)] [[Index](#index)] Index ----------------------- | ['Hello world' programs](#helloworld) [.NET Classes and Methods](#dotnetclassesandmethods) [.NET Help File](#dotnethelp) [A caution about insecure default algorithms](#cautionwithdefaults) [Acknowledgements](#acks) [Action if a self-test fails](#selftestfails) [Add an arbitrary X.509 Extension](#arbitraryx509extn) [Additional security attributes New in v12.4](#additionalsecurityattributes) [AOC policy for X.509 content](#aocpolicy) [ASN.1 analysis functions](#asn1functions) [ASN.1 objects: binary DER- and BER-encoded files vs PEM-encoded text files](#asn1objects) [Asn1 Class](#mx_Asn1) [AUTACK messages and ISO/IEC 9796-1 signatures](#autackmsgs) [Authenticated Encryption with Associated Data (AEAD)](#authencryptionaad) [Base64 alternative for X.509 certificates](#base64forcert) [Base64 and PEM string alternatives for CMS objects](#cmsbase64pem) [Base64url encoding and JSON Web Signatures (JWS)](#base64url) [Bibliography](#Bibliography) [Block Cipher Functions](#cipherfunctions) [C++ (STL) Functions](#cppfunctions) [C/C++ users must add one to this value...](#cusersaddone) [Can you read a key in compressed representation?](#compressedkey) [Cautions for C/C++ Users](#cautionsforcusers) [Certificate Revocation List (CRL) functions](#crlfunctions) [Changes in earlier versions](#changesearlier) [Cipher Class](#mx_Cipher) [CMS AuthEnvelopedData objects](#authenvelopeddata) [Cms Class](#mx_Cms) [CMS Content Types](#cmstypes) [CMS EnvelopedData objects](#envelopeddata) [CMS functions](#cmsfunctions) [CMS SignedData objects](#signeddata) [Cnv Class](#mx_Cnv) [Combining bitwise options](#bitwiseoptions) [Compiling with C](#compilingwithc) [Compr Class](#mx_Compr) [Compression functions](#comprfunctions) [Conditional Tests](#conditionaltests) [Continuous random number generator test:](#rngtest) [Conventions in this document](#Conventions) [Conversion functions](#cnvfunctions) [Converting strings to bytes and vice versa](#stringstobytes) [Converting VB6 to `VB.NET`](#vb6tovbnet) [Copyright Notice](#Copyright) [Core VBA/VB6 functions vs better wrapper functions](#corevbavswrappers) [Critical Errors](#criticalerrors) [Cross-reference between Functions and .NET Methods](#xrefdotnet) [Cryptographic algorithm test:](#cryptoalgtest) [Default encoding](#dndefaultencoding) [Detecting Win32 or X64 platform](#detectingplatform) [Ecc Class](#mx_Ecc) [Elliptic Curve Cryptography (ECC)](#eccrypto) [Elliptic curve cryptography functions](#eccfunctions) [Elliptic curve Diffie-Hellman (ECDH)](#ecdh) [Enumerations in .NET](#dotnetenumerations) [Error Handling and Error Codes](#errorcodes) [Examples of C code](#examplesccode) [eXtendable-output functions (XOF)](#xoffunctions) | [Filenames with 'International' characters](#filenamesinternational) [Find length of byte array](#findlengthbytearray) [General Class](#mx_General) [General functions](#genfunctions) [General Programming Issues](#generalprogramming) [Getting Started](#gettingstarted) [Hash Class](#mx_Hash) [HASH vs XOF vs MAC vs PRF vs KDF](#prfxof) [Hex format for NIST/SEC EC keys](#ecchexformat) [Hmac Class](#mx_Hmac) [HMAC Functions](#hmacfunctions) [Hpke Class](#mx_Hpke) [Hybrid Public Key Encryption (HPKE)](#hybridpke) [Hybrid Public Key Encryption (HPKE) functions](#hpkefunctions) [Index](#index) [Installation](#installation) [Intel(R) DRNG support](#inteldrng) [Internal key strings](#internalkeys) [Introduction to CryptoSys PKI Pro](#Introduction) [ISO 8601 date-time formats](#iso8601datetime) [ISO/IEC 9796-1 Formatting](#iso9796format) [Kdf Class](#mx_Kdf) [Key Derivation Functions](#kdffunctions) [Key Security](#keysecurity) [Key Storage Format (ECC)](#Keystorage-ecc) [Key Storage Format (RSA)](#Keystorage) [LDAP String Representation of Distinguished Names](#ldapstring) [List of .Net Methods](#methodlist) [List of Functions](#functionlist) [Message Digest Hash Functions](#hashfunctions) [New in this version](#newinthis) [Notes on VBA wrapper functions](#notesonvbawrapperfunctions) [Ocsp Class](#mx_Ocsp) [OCSP Functions](#ocspfunctions) [Optional Registry Settings](#registrysettings) [Other Issues For VB6/VBA Users](#otherissuesvb6) [Padding functions](#padfunctions) [Padding schemes for block ciphers](#paddingschemes) [Pair-wise consistency test:](#pairwiseconsistencytest) [Parameters for RSA-PSS and RSA-OAEP available in this Toolkit](#parametersrsapssoaep) [Passing a reference to an empty byte array in VB6/VBA](#passemptybytearray) [Password prompt functions](#promptfunctions) [Password-based encryption functions](#pbefunctions) [Pbe Class](#mx_Pbe) [Pem Class](#mx_Pem) [PEM string alternative for X.509 certificates, RSA and EC keys, etc](#pemstring) [PEM/binary file conversion functions](#pemfunctions) [Pfx Class](#mx_Pfx) [PFX Functions](#pfxfunctions) [Power-up Self-Tests](#powerupselftests) [Pre-dimensioning for VB6](#predimensioning) [Prf Class](#mx_Prf) [Primary References](#References) [Pseudorandom functions (PRF)](#prffunctions) [Pwd Class](#mx_Pwd) [Random Number Generator](#rnginfo) [Random number generator functions](#rngfunctions) [Raw RSA functions](#rawrsafunctions) | [Raw RSA Techniques](#rawrsa) [Return Values](#ReturnValues) [Revision History](#Revisions) [Rng Class](#mx_Rng) [RNG health test:](#rnghealthtest) [RNG Mechanisms](#rngmechanisms) [Rsa Class](#mx_Rsa) [RSA key functions](#rsafunctions) [RSA signature and encryption schemes: RSA-PSS and RSA-OAEP](#rsaschemes) [RSA2 Signing](#rsa2sign) [S/MIME functions](#smimefunctions) [Safe curves for elliptic cryptography](#eccsafecurves) [Security Issues](#securityissues) [Security options for encrypted private keys](#encryptedkeyoptions) [Self-Tests](#selftests) [Sig Class](#mx_Sig) [SIG functions](#sigfunctions) [Smime Class](#mx_Smime) [Software integrity test:](#softwareintegritytest) [Specifying an arbitrary RDN in a distinguished name](#arbitraryrdn) [Specifying Distinguished Names](#distnames) [Specifying the algorithm, mode and padding for generic block cipher functions](#cipheralgmode) [Specifying the signature algorithm in a SIG_ function](#sigalgorithm) [Summary of .NET Classes](#dotnetsummary) [Supported Algorithms](#SupportedAlgorithms) [Tdea Class](#mx_Tdea) [Technical Details](#technicaldetails) [Techniques to add known security strength to the RNG process](#rngtechniques) [Theory](#Theory) [Triple DES (TDEA/3DES) Functions](#tdeafunctions) [Type Conversions](#typeconversions) [Unsupported algorithms](#unsupportedalgorithms) [User-supplied entropy (seeds)](#rngentropy) [Using in MIME-conformant email messages](#usinginmime) [Using output in XML documents](#xmldocs) [Using with .NET: C# and `VB.NET`](#UsingWithDotNet) [Using with ANSI C](#UsingWithC) [Using With Borland C++](#borlandc) [Using with C++ (STL)](#UsingWithCpp) [Using with Classic Visual Basic VB6 and VBA](#UsingWithVB) [Using With MinGW gcc](#mingw) [Using with Python](#UsingWithPython) [UTF-8 and Latin-1](#utf8andlatin1) [UTF-8 encoding in distinguished names](#utf8forDN) [Valid key and block sizes for block cipher algorithms](#blockciphersizes) [VB6/C Function Summary](#vb6funcsummary) [VBA Wrapper Function List](#vbawrapperfunctionlist) [VBA Wrapper Functions](#vbawrapperfunctions) [Visual Basic or Visual Basic: VB6 vs `VB.NET`](#vb6vsvbdotnet) [Win64 (X64) Platform](#win64platform) [Wipe Class](#mx_Wipe) [Wipe functions](#wipefunctions) [X.509 certificate functions](#x509functions) [X.509 Extensions Parameter](#x509extensions) [X509 Class](#mx_X509) [Xof Class](#mx_Xof) [Zero-length byte arrays in VB6/VBA](#zerolengthbytearrays) | | --- | --- | --- | [[Contents](#topofpage)] [[Index](#index)] Revision History -------------------------------------- September 2025: Minor updates for markdown version. Updated links. 24 September 2024: Updated for Version 23.0. Added support for RSA-KEM with the Cryptographic Message Syntax (CMS). Added new features and improvements for CMS enveloped-data and signed-data creation. 1 January 2024: Updated for Version 22.1. Upgraded random number generator (RNG) functions. Added support for Intel(R) DRNG, if available. 23 October 2023: Updated for Version 22.0. Added support for elliptic curves Ed448 and X448, ChaCha20Poly1305 authenticated encryption, the SCRYPT password-based key derivation function, and Hybrid Public Key Encryption (HPKE) as per RFC9180. 1 January 2023: Updated for Version 21.0. Added support for SHA-3 and related functions. 10 September 2022: Updated for Version 20.6. Added support for CMS Authenticated-Enveloped-Data objects, and kekri and pwri recipientInfo types. 18 July 2022: Updated for Version 20.5. Added support for ECDH key agreement in enveloped-data objects and associated key derivation functions (KDF); and support for AES256-SHA256 encryption in PKCS#12 (PFX) files. 24 April 2022: Updated for Version 20.4. Added support for ECC Brainpool curves. 1 January 2022: Updated for Version 20.3. Added interface to C++ (STL). 3 October 2021: Updated for Version 20.2. Consolidated VBA modules for 32/64-bits and VBA wrapper functions. Rationalised .NET methods using .NET 4.0 optional parameters instead of .NET 2.0 overloads 13 March 2021: Updated for Version 20.1. 25 January 2021: Updated with documentation for VBA wrapper functions. 17 October 2020: Updated for Version 20.0. 12 May 2020: Updated for Version 12.4. Added additional security attributes for signed-data CMS objects. 6 March 2020: Updated for Version 12.3. Added support to generate GUID strings; added advanced options when creating X.509 certificates and PKCS#10 certificate requests; and support for stronger encryption for certificates in PKCS#12 (PFX) files. 12 July 2019: Updated for Version 12.2.30. A minor upgrade to fix issues with multithreading and running on XP. 20 May 2019: Updated for Version 12.2.20. A minor upgrade to fix multithreading issues. 24 March 2019: Updated for Version 12.2. Improved support for CMS (PKCS#7) signed-data and enveloped-data objects, and RSA keys represented in JSON Web Key (JWK) format. 17 November 2018: Updated for Version 12.1. Added support for AES-GCM. 19 June 2018: Updated for Version 12.0. Added support for RSA-PSS and RSA-OAEP; and support for ECDSA in X.509 certificates; and ZLIB compression. 28 April 2018: Updated for Version 11.3. Beta release for v12. 8 August 2017: Updated for Version 11.2. Various minor fixes and new convenience functions. 20 May 2016: Updated for Version 11.1. Added new block cipher functions. 8 March 2016: Updated for Version 11.0. Added elliptic curve cryptography. 27 March 2015: Updated for Version 10.0. Major update to CryptoSys PKI Pro. 2 September 2014: Updated for Version 3.10. Added block cipher functions with padding and password-based encryption (PBE) functions. 8 September 2012: Updated for Version 3.9 14 January 2012: Updated for Version 3.8 1 July 2011: Updated for Version 3.7 25 August 2010: Updated for Version 3.6 2 May 2010: Updated for Version 3.5 19 December 2009: Updated for Version 3.4. 19 February 2009: Updated for Version 3.3. 2 February 2008: Updated for Version 3.2. Added new block cipher functions and RSA-KEM (since withdrawn). 2 August 2007: Updated for Version 3.1. 27 March 2007: Updated for Version 3.0. Changes to RNG and internal key string storage. Added HMAC functions. 12 August 2006: Updated for Version 2.9. Major re-write of manual. 26 April 2006: Updated for Version 2.8. Added section on signed-data objects. 11 December 2005: Updated for Version 2.7. Added `VB.NET` and C# syntax prototypes, and index. 20 August 2005: Updated for Version 2.6. Added extra RSA functions for XML and message encoding, and support for PEM key files. Added section on Raw RSA Techniques. Added C/C++ syntax prototypes. 9 May 2005: Updated for Version 2.5. Added extra HASH and TDEA functions; rephrased action if self-test fails. 5 April 2005: Updated for Version 2.4. Added PFX functions and PEM export options. 1 March 2005: Updated for Version 2.3. 1 January 2005: Updated for Version 2.2. Added Boolean type description; added [in],[out] to parameters; other minor corrections. 29 November 2004: Minor corrections to manual. 24 November 2004: Updated for Version 2.1 September 2004: Minor amendments to manual. 25 February 2004: Version 2.0 manual first published by DI Management Services Pty Limited. December 2002: Proposed PKI functions first posted on . --- Copyright © 2004-25 D.I. Management Services Pty Ltd t/a CryptoSys ABN 78 083 210 584, Australia. All rights reserved. <[https://di-mgt.com.au](https://di-mgt.com.au "External link")> <[https://cryptosys.net](https://cryptosys.net "External link")> ---