Main Page   Modules   Data Structures   File List   Data Fields   Globals   Related Pages  

MQe_PrivateRegistry.h File Reference

MQePrivateRegistry object. More...


Functions

MQERETURN mqePrivateRegistry_new (MQeExceptBlock *pErrStruct, MQePrivateRegistryHndl *phPrivateRegistry)
MQERETURN mqePrivateRegistry_free (MQePrivateRegistryHndl hPrivateRegistry, MQeExceptBlock *pErrStruct)
MQERETURN mqePrivateRegistry_close (MQePrivateRegistryHndl hPrivateRegistry, MQeExceptBlock *pErrStruct)
MQERETURN mqePrivateRegistry_activate (MQePrivateRegistryHndl hPrivateRegistry, MQeExceptBlock *pErrStruct, MQeStringHndl hEntityName, MQeStringHndl hDirName, MQeStringHndl hPIN, MQeStringHndl hKeyRingPassword, MQeStringHndl hCertReqPIN, MQeStringHndl hCaIPAddrPort)
 Activates the PrivateRegistry.

MQERETURN mqePrivateRegistry_deleteCertificate (MQePrivateRegistryHndl hPrivateRegistry, MQeExceptBlock *pErrStruct, MQeStringHndl hCertificateOwner)
 Deletes the certificate owner’s mini-certificate.

MQERETURN mqePrivateRegistry_getCertificate (MQePrivateRegistryHndl hPrivateRegistry, MQeExceptBlock *pErrStruct, MQeFieldsHndl *phMiniCertificate, MQeStringHndl hCertificateOwner)
 Returns the certificate owner’s mini-certificate.

MQERETURN mqePrivateRegistry_getRegistryName (MQePrivateRegistryHndl hPrivateRegistry, MQeExceptBlock *pErrStruct, MQeStringHndl *phRegistryName)
 Return the owning entity name.

MQERETURN mqePrivateRegistry_resetPIN (MQePrivateRegistryHndl hPrivateRegistry, MQeExceptBlock *pErrStruct, MQeStringHndl hCurrentPIN, MQeStringHndl hNewPIN)
 Enables a valid private registry owner to change the access PIN.


Detailed Description

Provides controlled access to a set of private objects and public object (for example certificates). Also support digital signing and decryption services that can use the Registry's private objects (for example an authenticatable entity's private key) internally so they do not leave the private registry.


Function Documentation

MQERETURN mqePrivateRegistry_new MQeExceptBlock   pErrStruct,
MQePrivateRegistryHndl *    phPrivateRegistry
 

Creates a new Private Registry

Parameters:
pErrStruct  [in/out] Ptr to Error Structure
phPrivateRegistry  [out] Ptr to the new PrivateRegistry handle
Precondition:
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
Return values:
MQERETURN_OK  Completed Successfully

MQERETURN mqePrivateRegistry_free MQePrivateRegistryHndl    hPrivateRegistry,
MQeExceptBlock   pErrStruct
 

Frees the private registry handle

Parameters:
hPrivateRegistry  [in] Handle to the Private Registry to free
pErrStruct  [in/out] Ptr to Error Structure
Precondition:
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
Return values:
MQERETURN_OK  Completed Successfully

MQERETURN mqePrivateRegistry_close MQePrivateRegistryHndl    hPrivateRegistry,
MQeExceptBlock   pErrStruct
 

Closes the private registry handle

Parameters:
hPrivateRegistry  [in] Handle to the Private Registry to free
pErrStruct  [in/out] Ptr to Error Structure
Precondition:
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
Return values:
MQERETURN_OK  Completed Successfully

MQERETURN mqePrivateRegistry_activate MQePrivateRegistryHndl    hPrivateRegistry,
MQeExceptBlock   pErrStruct,
MQeStringHndl    hEntityName,
MQeStringHndl    hDirName,
MQeStringHndl    hPIN,
MQeStringHndl    hKeyRingPassword,
MQeStringHndl    hCertReqPIN,
MQeStringHndl    hCaIPAddrPort
 

If a private registry with this entityName exists activate() attempts to open the private registry using the given pin. If it does not exist activate() creates and opens a new private registry and makes it accessible via the given pin.

If a non-null mini-certificate server address (pCaIPAddrPort) is given, activate() searches the private Registry to discover if the owner is already registered (already has its own mini-certificate). IF it is not registered (no mini-certificate) activate() executes auto-Registration. This auto-registers the entityName performing the following tasks

  • Generates a new RSA key pair for the owning entityName
  • Saves the private key (CRTKey) in the private registry after protecting using a derivative of the given keyRingPassword
  • Packages the public key in a newCertificateRequest to the mini-certificate server address given, identifying the request with the entityName and the given (pre-allocated) mini-certificate request pin (certReqPin)
  • Saves the issued mini-certificate in the private registry then sends a getCertificate request to get the mini-certificate server's (own) mini-certificate and saves it in the private registry.
Parameters:
hPrivateRegistry  [in] Handle to the private registry to use
hErrStruct  [in/out] Ptr to Error Structure
hEntityName  [in] PrivateRegistry OwnerName
hDirName  [in] Handle to path to PrivateRegistry
hPIN  [in] Passphrase to be used to open the private registry.
hKeyRingPassword  [in] Passphrase used to protect the entity's private key.
hCertReqPin  [in] String with onetime use Certificate Request Number pre allocated for the entity by the mini-certificate server administrator to enable it to autoregister.
pCaIPAddrPort  [in] String with the TCP address and port of the solution's mini-certificate server.
Precondition:
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
Return values:
MQERETURN_OK  Completed Successfully
MQERETURN_J_PRIVATE_REG_BAD_PIN  Bad PIN number for private registry
MQERETURN_J_PRIVATE_REG_ACTIVATE_FAILED  Could not private registry

MQERETURN mqePrivateRegistry_deleteCertificate MQePrivateRegistryHndl    hPrivateRegistry,
MQeExceptBlock   pErrStruct,
MQeStringHndl    hCertificateOwner
 

Parameters:
hPrivateRegistry  [in] Handle to the private registry to use
pErrStruct  [in/out] Ptr to Error Structure
hCertificateOwner  [in] String of private registry owner's name
Precondition:
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
Return values:
MQERETURN_OK  Completed Successfully
MQERETURN_J_REG_DELETE_FAILED  Could not delete an entry to registry
MQERETURN_J_REG_DOES_NOT_EXIST  Registry does not exist

MQERETURN mqePrivateRegistry_getCertificate MQePrivateRegistryHndl    hPrivateRegistry,
MQeExceptBlock   pErrStruct,
MQeFieldsHndl *    phMiniCertificate,
MQeStringHndl    hCertificateOwner
 

Parameters:
hPrivateRegistry  [in] Handle to the private registry to use
pErrStruct  [in/out] Ptr to Error Structure
hCertificateOwner  [in] String of private registry owner's name
phMiniCertificate  [out] Ptr to MQeFields Handle with the mini-certificate
Precondition:
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
Return values:
MQERETURN_OK  Completed Successfully
MQERETURN_J_REG_READ_FAILED  Could not read an registry entry

MQERETURN mqePrivateRegistry_getRegistryName MQePrivateRegistryHndl    hPrivateRegistry,
MQeExceptBlock   pErrStruct,
MQeStringHndl *    phRegistryName
 

Use null or negative value for the size, to get the size set of the size of the name

Parameters:
hPrivateRegistry  [in] Handle to the private registry to use
pErrStruct  [in/out] Pointer to Error Structure
phRegistryName  [out] Pointer to registry name string
pSize  [out] Size of the name
Precondition:
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
Return values:
MQERETURN_OK  Completed Successfully

MQERETURN mqePrivateRegistry_resetPIN MQePrivateRegistryHndl    hPrivateRegistry,
MQeExceptBlock   pErrStruct,
MQeStringHndl    hCurrentPIN,
MQeStringHndl    hNewPIN
 

Parameters:
hPrivateRegistry  [in] Handle to the private registry to use
pErrStruct  [in/out] Pointer to Error Structure
pCurrentPIN  [in] Pointer to \0 terminated string of current pin.
pNewPIN  [in] Pointer to \0 terminated string of new pin.
Precondition:
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
Return values:
MQERETURN_OK  Completed Successfully


Generated Thu Aug 11 23:41:21 2005 for Websphere MQ Everyplace for Multiplatforms C Bindings Reference