libsecsipid.h: exported prototype for getting numberic option value

asipto · Mar 18, 2024 · 462a756 · 462a756
1 parent 0968c00
commit 462a756
Showing 1 changed file with 79 additions and 60 deletions.
diff --git a/csecsipid/libsecsipid.h b/csecsipid/libsecsipid.h
@@ -76,120 +76,139 @@ extern "C" {
 
 
 // SecSIPIDSignJSONHP --
-// * sign the JSON header and payload with provided private key file path
-// * headerJSON -  header part in JSON forman (0-terminated string)
-// * payloadJSON -  payload part in JSON forman (0-terminated string)
-// * prvkeyPath - path to private key to be used to generate the signature
-// * outPtr - to be set to the pointer containing the output (it is a
-//   0-terminated string); the `*outPtr` must be freed after use
-// * return: the length of `*outPtr`
+//   - sign the JSON header and payload with provided private key file path
+//   - headerJSON -  header part in JSON forman (0-terminated string)
+//   - payloadJSON -  payload part in JSON forman (0-terminated string)
+//   - prvkeyPath - path to private key to be used to generate the signature
+//   - outPtr - to be set to the pointer containing the output (it is a
+//     0-terminated string); the `*outPtr` must be freed after use
+//   - return: the length of `*outPtr`
+//
 extern int SecSIPIDSignJSONHP(char* headerJSON, char* payloadJSON, char* prvkeyPath, char** outPtr);
 
 // SecSIPIDSignJSONHPPrvKey --
-// * sign the JSON header and payload with provided private key data
-// * headerJSON -  header part in JSON forman (0-terminated string)
-// * payloadJSON -  payload part in JSON forman (0-terminated string)
-// * prvkeyData - private key data to be used to generate the signature
-// * outPtr - to be set to the pointer containing the output (it is a
-//   0-terminated string); the `*outPtr` must be freed after use
-// * return: the length of `*outPtr`
+//   - sign the JSON header and payload with provided private key data
+//   - headerJSON -  header part in JSON forman (0-terminated string)
+//   - payloadJSON -  payload part in JSON forman (0-terminated string)
+//   - prvkeyData - private key data to be used to generate the signature
+//   - outPtr - to be set to the pointer containing the output (it is a
+//     0-terminated string); the `*outPtr` must be freed after use
+//   - return: the length of `*outPtr`
+//
 extern int SecSIPIDSignJSONHPPrvKey(char* headerJSON, char* payloadJSON, char* prvkeyData, char** outPtr);
 
 // SecSIPIDGetIdentity --
 // Generate the Identity header content using the input attributes
-// * origTN - calling number
-// * destTN - called number
-// * attestVal - attestation level
-// * origID - unique ID for tracking purposes, if empty string a UUID is generated
-// * x5uVal - location of public certificate
-// * prvkeyPath - path to private key to be used to generate the signature
-// * outPtr - to be set to the pointer containing the output (it is a
-//   0-terminated string); the `*outPtr` must be freed after use
-// * return: the length of `*outPtr` on success or error return code (< 0)
+//   - origTN - calling number
+//   - destTN - called number
+//   - attestVal - attestation level
+//   - origID - unique ID for tracking purposes, if empty string a UUID is generated
+//   - x5uVal - location of public certificate
+//   - prvkeyPath - path to private key to be used to generate the signature
+//   - outPtr - to be set to the pointer containing the output (it is a
+//     0-terminated string); the `*outPtr` must be freed after use
+//   - return: the length of `*outPtr` on success or error return code (< 0)
+//
 extern int SecSIPIDGetIdentity(char* origTN, char* destTN, char* attestVal, char* origID, char* x5uVal, char* prvkeyPath, char** outPtr);
 
 // SecSIPIDGetIdentityPrvKey --
 // Generate the Identity header content using the input attributes
-// * origTN - calling number
-// * destTN - called number
-// * attestVal - attestation level
-// * origID - unique ID for tracking purposes, if empty string a UUID is generated
-// * x5uVal - location of public certificate
-// * prvkeyData - content of private key to be used to generate the signature
-// * outPtr - to be set to the pointer containing the output (it is a
-//   0-terminated string); the `*outPtr` must be freed after use
-// * return: the length of `*outPtr` on success or error return code (< 0)
+//   - origTN - calling number
+//   - destTN - called number
+//   - attestVal - attestation level
+//   - origID - unique ID for tracking purposes, if empty string a UUID is generated
+//   - x5uVal - location of public certificate
+//   - prvkeyData - content of private key to be used to generate the signature
+//   - outPtr - to be set to the pointer containing the output (it is a
+//     0-terminated string); the `*outPtr` must be freed after use
+//   - return: the length of `*outPtr` on success or error return code (< 0)
+//
 extern int SecSIPIDGetIdentityPrvKey(char* origTN, char* destTN, char* attestVal, char* origID, char* x5uVal, char* prvkeyData, char** outPtr);
 
 // SecSIPIDCheck --
 // check the Identity header value
-// * identityVal - identity header value
-// * identityLen - length of identityVal, if is 0, identityVal is expected
-//   to be 0-terminated
-// * expireVal - number of seconds until the validity is considered expired
-// * pubkeyPath - file path or URL to public key
-// * timeoutVal - timeout in seconds to try to fetch the public key via HTTP
-// * return: 0 - if validity is ok; <0 - on error or validity is not ok
+//   - identityVal - identity header value
+//   - identityLen - length of identityVal, if is 0, identityVal is expected
+//     to be 0-terminated
+//   - expireVal - number of seconds until the validity is considered expired
+//   - pubkeyPath - file path or URL to public key
+//   - timeoutVal - timeout in seconds to try to fetch the public key via HTTP
+//   - return: 0 - if validity is ok; <0 - on error or validity is not ok
+//
 extern int SecSIPIDCheck(char* identityVal, int identityLen, int expireVal, char* pubkeyPath, int timeoutVal);
 
 // SecSIPIDCheckFull --
 // check the Identity header value
-// * identityVal - identity header value with header parameters
-// * identityLen - length of identityVal, if it is 0, identityVal is expected
-//   to be 0-terminated
-// * expireVal - number of seconds until the validity is considered expired
-// * pubkeyPath - file path or URL to public key
-// * timeoutVal - timeout in seconds to try to fetch the public key via HTTP
-// * return: 0 - if validity is ok; <0 - on error or validity is not ok
+//   - identityVal - identity header value with header parameters
+//   - identityLen - length of identityVal, if it is 0, identityVal is expected
+//     to be 0-terminated
+//   - expireVal - number of seconds until the validity is considered expired
+//   - pubkeyPath - file path or URL to public key
+//   - timeoutVal - timeout in seconds to try to fetch the public key via HTTP
+//   - return: 0 - if validity is ok; <0 - on error or validity is not ok
+//
 extern int SecSIPIDCheckFull(char* identityVal, int identityLen, int expireVal, char* pubkeyPath, int timeoutVal);
 
 // SecSIPIDCheckFullPubKey --
 // check the Identity header value
-// * identityVal - identity header value with header parameters
-// * identityLen - length of identityVal, if it is 0, identityVal is expected
-//   to be 0-terminated
-// * expireVal - number of seconds until the validity is considered expired
-// * pubkeyVal - the value of the public key
-// * pubkeyLen - the length of the public key, if it is 0, then the pubkeyVal
-//   is expected to be 0-terminated
-// * return: 0 - if validity is ok; <0 - on error or validity is not ok
+//   - identityVal - identity header value with header parameters
+//   - identityLen - length of identityVal, if it is 0, identityVal is expected
+//     to be 0-terminated
+//   - expireVal - number of seconds until the validity is considered expired
+//   - pubkeyVal - the value of the public key
+//   - pubkeyLen - the length of the public key, if it is 0, then the pubkeyVal
+//     is expected to be 0-terminated
+//   - return: 0 - if validity is ok; <0 - on error or validity is not ok
+//
 extern int SecSIPIDCheckFullPubKey(char* identityVal, int identityLen, int expireVal, char* pubkeyVal, int pubkeyLen);
 
 // SecSIPIDSetFileCacheOptions --
 // set the options for local file caching of public keys
 // * dirPath - path to local directory where to store the files
 // * expireVal - number of the seconds after which to invalidate the cached file
 // * return: 0
+//
 extern int SecSIPIDSetFileCacheOptions(char* dirPath, int expireVal);
 
 // SecSIPIDGetURLContent --
 // get the content of an URL
-// * urlVal - the HTTP or HTTPS URL
-// * timeoutVal - timeout in seconds to try to get the content of the HTTP URL
-// * outPtr - to be set to the pointer containing the output (it is a
-//   0-terminated string); the `*outPtr` must be freed after use
-// * outLen: to be set to the length of `*outPtr`
-// * return: 0 - on success; -1 - on failure
+//   - urlVal - the HTTP or HTTPS URL
+//   - timeoutVal - timeout in seconds to try to get the content of the HTTP URL
+//   - outPtr - to be set to the pointer containing the output (it is a
+//     0-terminated string); the `*outPtr` must be freed after use
+//   - outLen: to be set to the length of `*outPtr`
+//   - return: 0 - on success; -1 - on failure
+//
 extern int SecSIPIDGetURLContent(char* urlVal, int timeoutVal, char** outPtr, int* outLen);
 
 // SecSIPIDOptSetS --
 // set a string option for the library
 // * optName - name of the option
 // * optVal - value of the option
 // * return: 0 if option was set, -1 otherwise
+//
 extern int SecSIPIDOptSetS(char* optName, char* optVal);
 
 // SecSIPIDOptSetN --
 // set a number (integer) option for the library
 // * optName - name of the option
 // * optVal - value of the option
 // * 0 if option was set, -1 otherwise
+//
 extern int SecSIPIDOptSetN(char* optName, int optVal);
 
+// SecSIPIDOptGetN --
+// get the number (integer) option from the library
+// * optName - name of the option
+// * return: option value if it was found, -1 otherwise
+//
+extern int SecSIPIDOptGetN(char* optName);
+
 // SecSIPIDOptSetV --
 // set an option for the library
 // * optNameVal - string with name=value of the option
 // * 0 if option was set, -1 otherwise
+//
 extern int SecSIPIDOptSetV(char* optNameVal);
 
 #ifdef __cplusplus