Back to the Function Reference Table of Contents
Key-Properties Functions
Extract the properties of a key or keys.
Visual Basic declaration:
Declare Function spgpkeyprops Lib "spgp.dll" (
ByVal KeyID As String,
ByVal KeyProps As String,
ByVal KeyPropsLen As Long
) As Long
Parameters:
KeyID
|
Target key ID, which can be either the e-mail address from the key's user-ID or the ID number of the key itself, which must be prefixed by "0x".
|
KeyProps
|
Properties of the target key. See Key Properties String.
|
KeyPropsLen
|
Size of KeyProps. If output exceeds KeyPropsLen the output will be discarded and the function will return a positive number indicating the size of the output (i.e. the buffer size necessary to hold it).
|
Notes and Warnings:
- KeyID may contain an ID for one key or multiple ID strings separated by commas. Please see the author's stern warnings about ID strings and multiple recipients.
- Starting with SPGP 2.5, this function may optionally return new-style key properties. Ultimately this and other functions will have a "Flags" property for passing the bit-flags indicating which properties to return. In the meantime, the developer can pass the flags in this way: (1) combine the desired constants via bitwise OR; (2) convert the result to a string; (3) pass the string to the function in the BufferOut parameter. If BufferOut is empty, old-style key properties will be returned as usual. Visual Basic users can see a demonstration of this technique in the VB5Project application, under the button labeled "Key Props Test".
up to the top
Extract the ID strings of all the keys on the default key-ring.
Visual Basic declaration:
Declare Function spgpkeyringid Lib "spgp.dll" (
ByVal BufferOut As String,
ByVal BufferOutLen As Long
) As Long
BufferOut
|
A fixed-length string which will act as a buffer for output.
|
BufferOutLen
|
Size of BufferOut. If output exceeds BufferOutLen the output will be discarded and the function will return a positive number indicating the size of the output (i.e. the buffer size necessary to hold it).
|
Notes and Warnings:
- This function allows the developer to access the main identifying properties of all the keys on the key ring. The first version was a wrapper which called spgpKeyProps for each available key, but it was realized that the resulting string could be excessively large. To conserve resources, the current version returns only the key's type and ID strings. To extract the full properties of a given key, the developer should select the desired ID string and use that to call spgpKeyProps.
- A typical use is illustrated in the accompanying sample program: spgpKeyRingID is used to populate a ListBox with ID strings, which the user selects to view full key properties via spgpKeyProps, or double-clicks to extract the selected key via spgpKeyExport.
- The output of this function is identical to the first three property strings of a Key Properties String: A boolean value indicating whether or not a private key is present, a TAB character, a key ID number, a TAB character, and the primary user-ID string. Each key's string is terminated with a CRLF pair.
- To get a general idea of how large a buffer will be necessary for the output, the developer can call spgpKeyRingCount and multiply the result by a suitable number of bytes for each anticipated abbreviated key-property string.
- Starting with SPGP 2.5, this function may optionally return new-style key properties. Ultimately this and other functions will have a "Flags" property for passing the bit-flags indicating which properties to return. In the meantime, the developer can pass the flags in this way: (1) combine the desired constants via bitwise OR; (2) convert the result to a string; (3) pass the string to the function in the BufferOut parameter. If BufferOut is empty, old-style key properties will be returned as usual. Visual Basic users can see a demonstration of this technique in the VB5Project application, under the button labeled "Key Props Test".
up to the top
Extract the properties of all the keys on the default key-ring and save them to a text file.
Visual Basic declaration:
Declare Function spgpkeyringtofile Lib "spgp.dll" (
ByVal FileOut As String
) As Long
FileOut
|
Output file. This must be a complete path and file name.
|
Notes and Warnings:
up to the top
Returns the number of keys on the default key-ring.
Visual Basic declaration:
Declare Function spgpkeyringcount Lib "spgp.dll" () As Long
Notes and Warnings:
- The result will be the number of keys on the local ring. A key-pair is counted as a single key. It is possible for an empty ring to return "0", but any negative number should be treated as an error code.
- One use for this function is estimating how large a buffer will be necessary when calling spgpKeyRingID, the output of which is otherwise unpredictable.
up to the top
Verifies the presence of a key on the default key-rings.
Visual Basic declaration:
Declare Function spgpkeyisonring Lib "spgp.dll" (
ByVal KeyID As String
) As Long
Parameters:
KeyID
|
The key to search for. The ID may be either a Key ID (e.g. 0x123456) or a User ID enclosed in angle brackets (e.g. <test@test.com>). Unlike the other functions taking Key IDs as parameters, this function accepts only one ID at a time.
|
Notes and Warnings:
- The function returns zero if the key is found. Any other result should be treated as an error code.
- Keep in mind that an error code may result from the Key ID being inaccurate or malformed.
up to the top
Extracts all the user IDs from a key.
Visual Basic declaration:
Declare Function spgpkeypropuserid Lib "spgp.dll" (
ByVal KeyID As String,
ByVal BufferOut As String,
ByVal BufferOutLen As Long
) As Long
Parameters:
KeyID
|
Target key's key ID, which can be either the e-mail address from the key's User ID or the ID number of the key itself, which must be prefixed by "0x".
|
BufferOut
|
A fixed-length string which will act as a buffer for output.
|
BufferOutLen
|
Size of BufferOut. If output exceeds BufferOutLen the output will be discarded and the function will return a positive number indicating the size of the output (i.e. the buffer size necessary to hold it).
|
Notes and Warnings:
- BufferOut will contain a tab-delimited string containing all the user IDs (i.e., name and e-mail address) for the target key. The key's primary ID will be first, and any additional IDs will follow in no particular order.
up to the top
Extracts the key ID from the signature(s) on a key's User ID.
Visual Basic declaration:
Declare Function spgpkeypropsig Lib "spgp.dll" (
ByVal UserID As String,
ByVal BufferOut As String,
ByVal BufferOutLen As Long
) As Long
Parameters:
UserID
|
Target user ID, which must be a complete User ID, i.e., name and e-mail address.
|
BufferOut
|
A fixed-length string which will act as a buffer for output.
|
BufferOutLen
|
Size of BufferOut. If output exceeds BufferOutLen the output will be discarded and the function will return a positive number indicating the size of the output (i.e. the buffer size necessary to hold it).
|
Notes and Warnings:
- BufferOut will contain a tab-delimited string containing a hexidecimal key ID for each signature certificate attached to the target user ID.
- If there are no signatures, BufferOut will be empty; a lack of signatures will not generate an error.
- Unlike most other SPGP functions, the target key must be identified by a complete User ID. The User ID must be an exact match, so this function is also case-sensitive.
up to the top
Extracts the properties of a key's Additional Decryption Key(s), if any.
Visual Basic declaration:
Declare Function spgpkeypropadk Lib "spgp.dll" (
ByVal KeyHexID As String,
ByVal ADKProps As String,
ByVal ADKPropsLen As Long,
ADKCount As Long,
ByVal Flags As Long
) As Long
Parameters:
KeyHexID
|
Target Key, which must be a Hex ID.
|
ADKProps
|
A fixed-length string which will act as a buffer for output (i.e., the properties of the ADK).
|
ADKPropsLen
|
Size of ADKProps. If output exceeds ADKPropsLen the output will be discarded and the function will return a positive number indicating the size of the output (i.e. the buffer size necessary to hold it).
|
ADKCount
|
The number of Additional Decryption Keys found.
|
Flags
|
Bit-flags indicating which key properties to return. See the Notes below for details on the format of the output.
|
Notes and Warnings:
- This function returns the new-style key-properties strings.
- If the ADK is on the local ring, ADKProps will contain the properties indicated by the Flags parameter; otherwise it will contain a hexidecimal key ID and, optionally, a value indicating the presence of an enforced ADK (see below).
- To test for an enforced ADK (i.e., one which requests that clients refuse to encrypt to the target key without the ADK), include PGPKeyPropFlag_HasADK in the Flags parameter. In the context of this function only, the resulting item should be interpreted as a boolean property meaning "has enforced ADK".
Examples of output. The first ADK is on the local ring, the second is not. The first ADK is enforced, the second is not. In both cases Flags = PGPKeyPropFlag_KeyID Or PGPKeyPropFlag_UserID Or PGPKeyPropFlag_HasADK
.
0xDEDB8A53 Steve Heller <sh@neuropa.net> 1
0xB670E1D0 0
Note that if the key isn't on the local ring, the output will contain the hex ID, regardless of the Flags parameter.
up to the top
Extracts the properties of a key's designated revocation key(s), if any.
Visual Basic declaration:
Declare Function spgpkeyproprevocationkey Lib "spgp.dll" (
ByVal KeyHexID As String,
ByVal RevKeyProps As String,
ByVal RevKeyPropsLen As Long,
RevKeyCount As Long,
ByVal Flags As Long
) As Long
Parameters:
KeyHexID
|
Target Key, which must be a Hex ID.
|
RevKeyProps
|
A fixed-length string which will act as a buffer for output (i.e., the properties of the revocation key).
|
RevKeyPropsLen
|
Size of RevKeysProps. If output exceeds RevKeyPropsLen the output will be discarded and the function will return a positive number indicating the size of the output (i.e. the buffer size necessary to hold it).
|
RevKeyCount
|
The number of revocation keys found.
|
Flags
|
Bit-flags indicating which key properties to return.
|
Notes and Warnings:
- If the revocation key is on the local ring, RevKeyProps will contain the properties indicated by the Flags parameter; otherwise it will contain a hexidecimal key ID.
Back to the Function Reference Table of Contents