osptnepenroll.h

mgcp协议源代码。支持多种编码：g711

 * relies on OSPPUtilGetRandom, for generating the random bytes of the nonce. 
 * Since OSPPUtilGetRandom doesn't rely on anything special for the
 * entropy of these random values, it would be best to either modify 
 * OSPPUtilGetRandom or just pass the value of the nonce in ( so that we
 * don't generate it here. )
 *
 * Input: reference to a string and its length to write to, as well as a
 *        length that specifies how long the nonce should be.
 *
 * Output: OSPC_ERR_NO_ERROR if there aren't any problems; in this case, 
 *         the *ospvNonceOut should be non-null and *ospvNonceLenOut should
 *         specify its length. Otherwise, an error code other than 
 *         OSPC_ERR_NO_ERROR will be returned if a problem comes up. In this
 *         case, *ospvNonceOut should be OSPC_OSNULL and *ospvNonceLenOut
 *         should be 0 ( but this isn't guaranteed, especially if 
 *         ospvNonceOut or ospvNonceLenOut were OSPC_OSNULL to begin with. )
 */
int OSPPCreateNonce(
    unsigned char** ospvNonceOut,
    unsigned*       ospvNonceLenOut,
    unsigned        ospvNonceLenIn
);

/*
 * Given a character string that will eventually be sent to an enrollment
 * server as part of a MsgInfo's Request, add a name-value pair that reflects
 * an enrollment parameter. 
 *
 * Input: the request's character string, plus the k
 *
 *
 */
int OSPPAddNameValuePair(
    unsigned char* ospvDestStr,
    unsigned char* ospvName,
    unsigned       ospvNameLen,
    unsigned char* ospvValue,
    unsigned       ospvValueLen,
    unsigned       ospvPrependAmpersand
);

/* Given a source string of characters, URL-encode it and append it to
 * the destination string:
 */
int OSPPAppendUrlEncodedString (
    unsigned char* destStr,
    unsigned char* srcStr,
    unsigned       srcStrLen
);

/*
 * Given a MessageInfo structure, extract the status from the "status=" field
 * that's contained in the Response field. If the status field cannot be found,
 * then this function will return an error.
 */
int OSPPGetStatusFromResponse (
    const OSPTMSGINFO* ospvMsgInfo,
    unsigned* ospvEnrollStatusOut
);

/*
 * Given a MessageInfo structure, extract the certificate from it. There
 * is no need to check the base64 encoding of the certificate or any other
 * structural constraints.
 */
int OSPPGetCertificateFromResponse (
    const OSPTMSGINFO* ospvMsgInfo,
    unsigned char*     ospvCertOut,
    unsigned*          ospvCertLenOut
);

/*
 * Given the CA certificate and a certificate that is supposedly for the
 * router, check its validity. That is, decode the base64 encoding of the
 * certificate, make sure that it's an X.509 cert, that it has the correct
 * version ( 2, to indicate a version 3 cert ); and that it's signed by
 * the CA. This should also include something for checking the public key
 * at some point.
 */
int OSPPValidateCert (
    const unsigned char* ospvCACertIn,
    const unsigned char* ospvCertIn,
    const unsigned ospvCertLenIn,
    const OSPTASN1OBJECT* ospvSubjectPublicKeyInfoIn,
    OSPTASN1OBJECT* ospvCertOut
);

/*
 * Compare the two ASN1 objects. Returns OSPC_ERR_NO_ERROR if they're the
 * same, and a non-zero value otherwise.
 *
 * Input:
 *   ospvLHSObject: a pointer to an ASN1 Object ( the LeftHand Side )
 *   ospvRHSObject: a pointer to an ASN1 Object ( the RightHand Side )
 *
 * Output:
 *   OSPC_ERR_NO_ERROR if the two are the same, or some other value otherwise.
 *
 * Errors: Errors will be returned when
 *   o at least one of the parameters is null ( OSPC_ERR_ENROLL_INVALID_PARAMS )
 *   o the two have different lengths ( OSPC_ERR_ENROLL_LENGTH_MISMATCH );
 *   o the two have different contents ( OSPC_ERR_ENROLL_CONTENT_MISMATCH );
 */
int OSPPASN1Compare (
    OSPTASN1OBJECT* ospvLHSObject,
    OSPTASN1OBJECT* ospvRHSObject
);


/*
 * This is for constructing the enrollment request that is sent to the 
 * enrollment server; the output is an OSPTMSGINFO structure that
 * contains it.
 *
 * Input: A pointer to the enrollment parameters and to the MessageInfo that
 *        contains the parameters for the enrollment request.
 *
 * Output: The OSPTMSGINFO should contain all of the information necessary
 *         for transmitting a request to the enrollment server. In this case,
 *         the return value will be OSPC_ERR_NO_ERROR. If something
 *         goes wrong, then the return value will be something other than
 *         OSPC_ERR_NO_ERROR. In that case, there is no guarantee about what
 *         the OSPTMSGINFO* structure will contain.
 */
int OSPPConstructEnrollmentRequest (
    OSPTENROLLPARAMS* ospvEnrollParamsIn,
    OSPTMSGINFO*      ospvMsgInfoOut
);

/* 
 * Given a base64 encoding of a certificate request, retrieve the 
 * subjectPublicKeyInfo from that certificate request and store it in the
 * given ASN.1 element info's placeholder. 
 *
 * Input: base64 certificate request 
 *        ( unsigned char* ospvBase64CertReq )
 *
 * Output: *ospvPublicKeyInfoOut should, if successful, contain the 
 *         subjectPublicKeyInfo of the certificate request. If not, then 
 *         an errorcode should be returned.
 *
 * Errors: Errorcodes other than OSPC_ERR_NO_ERROR are returned when:
 *     o either parameter is null;
 *     o memory cannot be allocated for ephemeral variables;
 *     o the certificate request is improperly base64 encoded;
 *     o the certificate request is invalid ( i.e., the subjectPublicKeyInfo
 *       could not be found in the desired location );
 */
int OSPPGetPublicKeyInfoFromCertReq( 
    unsigned char*   ospvBase64CertReq,
    OSPTASN1OBJECT*  ospvPublicKeyInfoOut 
);

/* Given a character string, make sure that it's valid: it's non-null,
 * and has nothing but ascii characters:
 */
int OSPPValidateAsciiString( 
    unsigned char* ospvAlnumStr 
);

/* Given a string of digits, make sure that it's valid: it's non-null,
 * and has nothing but digits.
 */
int OSPPValidateDigitString( 
    unsigned char* ospvDigitStr
); 

/* Given an ASN1 object that represents an X.509 certificate, store its
 * subjectPublicKeyInfo in the outbound ospvPublicKeyOut structure.
 * This subjectPublicKeyInfo will be compared against what we get from
 * the server in the form of a certificate; if they match, then the
 * certificate may be ok - otherwise, the certificate is bogus.
 *
 * Input: references to the input certificate and the outgoing 
 *        subjectPublicKeyInfo
 *
 * Output: If the subjectPublicKeyInfo can be found, then it should be
 *         stored in *ospvPublicKeyOut and the return value will be
 *         OSPC_ERR_NO_ERROR. Otherwise, the return value will be
 *         something other than OSPC_ERR_NO_ERROR.
 */
int OSPPGetPublicKeyInfoFromCert( 
    OSPTASN1OBJECT*  ospvCertIn, 
    OSPTASN1OBJECT*  ospvPublicKeyOut 
);

/* Given a binary string that represents a PKCS#10 request, create an
 * ASN1 object that contains the subjectPublicKeyInfo of the certificate
 * request. The subjectPublicKeyInfo is found as follows:
 *
 * SEQUENCE CertificateRequest        
 *     SEQUENCE certificateRequestInfo 
 *         INTEGER  version 
 *         SEQUENCE subjectName 
 *         SEQUENCE subjectPublicKeyInfo 
 *         SEQUENCE attributes
 *     OID signatureAlgorithm
 *     BIT STRING signature
 *
 * We'll use the ASN1 module from the OSP to decode the binary string
 * and extract the public key from the certificate request.
 *
 * Input: string representing a PKCS#10 certificate request, and a pointer
 *        to an ASN1 object for storing its subjectPublicKeyInfo.
 *
 * Output: the subjectPublicKeyInfo should be found, in which case we'll
 *         return OSPC_ERR_NO_ERROR. Otherwise, a different error code will
 *         be returned.
 */
int OSPPGetPublicKeyInfoFromCertReq(
    unsigned char*   ospvCertReqIn, 
    OSPTASN1OBJECT*  ospvPublicKeyOut 
); 

/* Cleanup the communications manager: its HTTP connections, security manager,
 * and the communications manager itself. The only way that this function
 * will return an error is if the communications manager passed in for deletion
 * is null.
 *
 * Input: reference to the communications manager pointer to be deleted.
 */
int OSPPEnrollCleanupCommMgr (
    OSPTCOMM** ospvCommMgrIn
);

#ifdef __cplusplus
}
#endif