Documentation Fixes (#1520)

* Fixed documentation errors found by check_api script
* Formatting changes so that comments/API pairs are more obvious
pull/1524/head
connerWolfSSL 2018-04-27 10:50:34 -06:00 committed by David Garske
parent c1d4f659ad
commit e45f0efc3f
13 changed files with 79 additions and 80 deletions

View File

@ -20,6 +20,7 @@
\sa wc_MakeCertReq
*/
WOLFSSL_API int wc_InitCert(Cert*);
/*!
\ingroup ASN
@ -65,6 +66,7 @@ WOLFSSL_API int wc_InitCert(Cert*);
*/
WOLFSSL_API int wc_MakeCert(Cert*, byte* derBuffer, word32 derSz, RsaKey*,
ecc_key*, WC_RNG*);
/*!
\ingroup ASN
@ -109,8 +111,9 @@ WOLFSSL_API int wc_MakeCert(Cert*, byte* derBuffer, word32 derSz, RsaKey*,
\sa wc_InitCert
\sa wc_MakeCert
*/
WOLFSSL_API int wc_MakeCertReq(Cert*, byte* derBuffer, word32 derSz,
WOLFSSL_API int wc_MakeCertReq(Cert*, byte* derBuffer, word32 derSz,
RsaKey*, ecc_key*);
/*!
\ingroup ASN
@ -163,6 +166,7 @@ WOLFSSL_API int wc_MakeCert(Cert*, byte* derBuffer, word32 derSz, RsaKey*,
*/
WOLFSSL_API int wc_SignCert(int requestSz, int sigType, byte* derBuffer,
word32 derSz, RsaKey*, ecc_key*, WC_RNG*);
/*!
\ingroup ASN
@ -208,6 +212,7 @@ WOLFSSL_API int wc_SignCert(int requestSz, int sigType, byte* derBuffer,
*/
WOLFSSL_API int wc_MakeSelfCert(Cert*, byte* derBuffer, word32 derSz, RsaKey*,
WC_RNG*);
/*!
\ingroup ASN
@ -270,6 +275,7 @@ WOLFSSL_API int wc_MakeSelfCert(Cert*, byte* derBuffer, word32 derSz, RsaKey*,
\sa wc_SetIssuerBuffer
*/
WOLFSSL_API int wc_SetIssuer(Cert*, const char*);
/*!
\ingroup ASN
@ -328,6 +334,7 @@ WOLFSSL_API int wc_SetIssuer(Cert*, const char*);
\sa wc_SetIssuer
*/
WOLFSSL_API int wc_SetSubject(Cert*, const char*);
/*!
\ingroup ASN
@ -387,7 +394,8 @@ WOLFSSL_API int wc_SetSubject(Cert*, const char*);
\sa wc_InitCert
\sa wc_SetIssuer
*/
WOLFSSL_API int wc_SetAltNames(Cert*, const char*);
WOLFSSL_API int wc_SetAltNames(Cert*, const char*);
/*!
\ingroup ASN
@ -453,6 +461,7 @@ WOLFSSL_API int wc_SetSubject(Cert*, const char*);
\sa wc_SetIssuer
*/
WOLFSSL_API int wc_SetIssuerBuffer(Cert*, const byte*, int);
/*!
\ingroup ASN
@ -517,6 +526,7 @@ WOLFSSL_API int wc_SetIssuerBuffer(Cert*, const byte*, int);
\sa wc_SetSubject
*/
WOLFSSL_API int wc_SetSubjectBuffer(Cert*, const byte*, int);
/*!
\ingroup ASN
@ -584,6 +594,7 @@ WOLFSSL_API int wc_SetSubjectBuffer(Cert*, const byte*, int);
\sa wc_SetAltNames
*/
WOLFSSL_API int wc_SetAltNamesBuffer(Cert*, const byte*, int);
/*!
\ingroup ASN
@ -648,6 +659,7 @@ WOLFSSL_API int wc_SetAltNamesBuffer(Cert*, const byte*, int);
\sa wc_InitCert
*/
WOLFSSL_API int wc_SetDatesBuffer(Cert*, const byte*, int);
/*!
\ingroup ASN
@ -711,6 +723,7 @@ WOLFSSL_API int wc_SetAuthKeyIdFromPublicKey(Cert *cert, RsaKey *rsakey,
\sa wc_SetAuthKeyId
*/
WOLFSSL_API int wc_SetAuthKeyIdFromCert(Cert *cert, const byte *der, int derSz);
/*!
\ingroup ASN
@ -739,6 +752,7 @@ WOLFSSL_API int wc_SetAuthKeyIdFromCert(Cert *cert, const byte *der, int derSz);
\sa wc_SetAuthKeyIdFromCert
*/
WOLFSSL_API int wc_SetAuthKeyId(Cert *cert, const char* file);
/*!
\ingroup ASN
@ -771,6 +785,7 @@ WOLFSSL_API int wc_SetAuthKeyId(Cert *cert, const char* file);
*/
WOLFSSL_API int wc_SetSubjectKeyIdFromPublicKey(Cert *cert, RsaKey *rsakey,
ecc_key *eckey);
/*!
\ingroup ASN
@ -801,6 +816,7 @@ WOLFSSL_API int wc_SetSubjectKeyIdFromPublicKey(Cert *cert, RsaKey *rsakey,
\sa wc_SetSubjectKeyIdFromPublicKey
*/
WOLFSSL_API int wc_SetSubjectKeyId(Cert *cert, const char* file);
/*!
\ingroup ASN
@ -833,7 +849,8 @@ WOLFSSL_API int wc_SetSubjectKeyId(Cert *cert, const char* file);
*/
WOLFSSL_API int wc_SetSubjectKeyIdFromNtruPublicKey(Cert *cert, byte *ntruKey,
word16 ntruKeySz);
/*!
/*!
\ingroup RSA
\brief This function allows you to set the key usage using a comma
@ -864,8 +881,9 @@ WOLFSSL_API int wc_SetSubjectKeyIdFromNtruPublicKey(Cert *cert, byte *ntruKey,
\sa wc_InitCert
\sa wc_MakeRsaKey
*/
*/
WOLFSSL_API int wc_SetKeyUsage(Cert *cert, const char *value);
/*!
\ingroup ASN
@ -916,6 +934,7 @@ WOLFSSL_API int wc_SetKeyUsage(Cert *cert, const char *value);
WOLFSSL_API int wc_MakeNtruCert(Cert*, byte* derBuffer, word32 derSz,
const byte* ntruKey, word16 keySz,
WC_RNG*);
/*!
\ingroup ASN
@ -946,6 +965,7 @@ WOLFSSL_API int wc_MakeNtruCert(Cert*, byte* derBuffer, word32 derSz,
*/
WOLFSSL_API int wc_PemPubKeyToDer(const char* fileName,
unsigned char* derBuf, int derSz);
/*!
\ingroup ASN
@ -976,8 +996,8 @@ WOLFSSL_API int wc_PemPubKeyToDer(const char* fileName,
\sa wc_PemPubKeyToDer
*/
WOLFSSL_API int wc_PubKeyPemToDer(const unsigned char*, int,
unsigned char*, int);
unsigned char*, int);
/*!
\ingroup ASN
@ -1011,7 +1031,7 @@ WOLFSSL_API int wc_PubKeyPemToDer(const unsigned char*, int,
\sa none
*/
WOLFSSL_API
int wc_PemCertToDer(const char* fileName,unsigned char* derBuf,int derSz);
int wc_PemCertToDer(const char* fileName, unsigned char* derBuf, int derSz);
/*!
\ingroup ASN
@ -1053,8 +1073,9 @@ int wc_PemCertToDer(const char* fileName,unsigned char* derBuf,int derSz);
\sa wc_PemCertToDer
*/
WOLFSSL_API int wc_DerToPem(const byte* der, word32 derSz, byte* output,
WOLFSSL_API int wc_DerToPem(const byte* der, word32 derSz, byte* output,
word32 outputSz, int type);
/*!
\ingroup ASN
@ -1097,7 +1118,7 @@ int wc_PemCertToDer(const char* fileName,unsigned char* derBuf,int derSz);
\sa wc_PemCertToDer
*/
WOLFSSL_API int wc_DerToPemEx(const byte* der, word32 derSz, byte* output,
WOLFSSL_API int wc_DerToPemEx(const byte* der, word32 derSz, byte* output,
word32 outputSz, byte *cipherIno, int type);
/*!
@ -1137,6 +1158,7 @@ int wc_PemCertToDer(const char* fileName,unsigned char* derBuf,int derSz);
*/
WOLFSSL_API int wc_KeyPemToDer(const unsigned char*, int,
unsigned char*, int, const char*);
/*!
\ingroup CertsKeys
@ -1168,35 +1190,7 @@ WOLFSSL_API int wc_KeyPemToDer(const unsigned char*, int,
*/
WOLFSSL_API int wc_CertPemToDer(const unsigned char*, int,
unsigned char*, int, int);
/*!
\ingroup CertsKeys
\brief Converts the PEM format to DER format.
\return int an int type representing the bytes written to buffer.
\param <0 returned for an error.
\param BAD_FUNC_ARG returned if the DER length is incorrect or if the
pem buff, or buffSz arguments are NULL.
_Example_
\code
unsigned char* pem = pem file;
int pemSz = sizeof(pem)/sizeof(char);
unsigned char* buff;
int buffSz;
...
if(wc_PubKeyPemToDer(pem, pemSz, buff, buffSz)!= SSL_SUCCESS){
// Conversion was not successful
}
\endcode
\sa wc_PubKeyPemToDer
\sa wc_PemPubKeyToDer
\sa wc_PemToDer
*/
WOLFSSL_API int wc_PubKeyPemToDer(const unsigned char*, int,
unsigned char*, int);
/*!
\ingroup ASN
@ -1246,7 +1240,7 @@ WOLFSSL_API int wc_CertPemToDer(const unsigned char*, int,
// read key into tmp buffer
wc_ecc_init(&key); // initialize key
ret = wc_Ecc_PrivateKeyDecode(tmp, &idx, &key, (word32)inSz);
ret = wc_EccPrivateKeyDecode(tmp, &idx, &key, (word32)inSz);
if(ret < 0) {
// error decoding ecc key
}
@ -1254,8 +1248,9 @@ WOLFSSL_API int wc_CertPemToDer(const unsigned char*, int,
\sa wc_RSA_PrivateKeyDecode
*/
WOLFSSL_API int wc_EccPrivateKeyDecode(const byte*, word32*,
WOLFSSL_API int wc_EccPrivateKeyDecode(const byte*, word32*,
ecc_key*, word32);
/*!
\ingroup ASN
@ -1298,7 +1293,8 @@ WOLFSSL_API int wc_CertPemToDer(const unsigned char*, int,
\sa wc_RsaKeyToDer
*/
WOLFSSL_API int wc_EccKeyToDer(ecc_key*, byte* output, word32 inLen);
WOLFSSL_API int wc_EccKeyToDer(ecc_key*, byte* output, word32 inLen);
/*!
\ingroup ASN
@ -1331,8 +1327,9 @@ WOLFSSL_API int wc_CertPemToDer(const unsigned char*, int,
\sa wc_ecc_import_x963
*/
WOLFSSL_API int wc_EccPublicKeyDecode(const byte*, word32*,
WOLFSSL_API int wc_EccPublicKeyDecode(const byte*, word32*,
ecc_key*, word32);
/*!
\ingroup ASN
@ -1371,8 +1368,9 @@ WOLFSSL_API int wc_CertPemToDer(const unsigned char*, int,
\sa wc_EccKeyToDer
\sa wc_EccPrivateKeyDecode
*/
WOLFSSL_API int wc_EccPublicKeyToDer(ecc_key*, byte* output,
WOLFSSL_API int wc_EccPublicKeyToDer(ecc_key*, byte* output,
word32 inLen, int with_AlgCurve);
/*!
\ingroup ASN
@ -1408,6 +1406,7 @@ WOLFSSL_API int wc_CertPemToDer(const unsigned char*, int,
*/
WOLFSSL_API word32 wc_EncodeSignature(byte* out, const byte* digest,
word32 digSz, int hashOID);
/*!
\ingroup ASN

View File

@ -81,7 +81,7 @@ WOLFSSL_API int wc_Blake2bUpdate(Blake2b*, const byte*, word32);
wc_InitBlake2b(&b2b, 64);
... // call wc_Blake2bUpdate to add data to hash
ret = 2c_Blake2bFinal(&b2b, hash, 64);
ret = wc_Blake2bFinal(&b2b, hash, 64);
if( ret != 0) {
// error generating blake2b hash
}

View File

@ -85,7 +85,7 @@ WOLFSSL_API int wc_CamelliaSetIV(Camellia* cam, const byte* iv);
byte plain[] = { // initialize with message to encrypt };
byte cipher[16];
wc_CamelliaEncrypt(&ca, cipher, plain);
wc_CamelliaEncryptDirect(&ca, cipher, plain);
\endcode
\sa wc_CamelliaDecryptDirect

View File

@ -74,8 +74,8 @@ WOLFSSL_API int Base64_Decode(const byte* in, word32 inLen, byte* out,
\sa Base64_EncodeEsc
\sa Base64_Decode
*/
WOLFSSL_API
int Base64_Encode(const byte* in, word32 inLen, byte* out,
WOLFSSL_API
int Base64_Encode(const byte* in, word32 inLen, byte* out,
word32* outLen);
/*!
\ingroup Base_Encoding
@ -116,7 +116,7 @@ WOLFSSL_API int Base64_Decode(const byte* in, word32 inLen, byte* out,
\sa Base64_Encode
\sa Base64_Decode
*/
int Base64_EncodeEsc(const byte* in, word32 inLen, byte* out,
int Base64_EncodeEsc(const byte* in, word32 inLen, byte* out,
word32* outLen);
/*!
\ingroup Base_Encoding
@ -154,8 +154,8 @@ WOLFSSL_API int Base64_Decode(const byte* in, word32 inLen, byte* out,
\sa Base64_Encode
\sa Base64_Decode
*/
WOLFSSL_API
int Base64_Encode_NoNl(const byte* in, word32 inLen, byte* out,
WOLFSSL_API
int Base64_Encode_NoNl(const byte* in, word32 inLen, byte* out,
word32* outLen);
/*!
\ingroup Base_Encoding
@ -192,8 +192,8 @@ WOLFSSL_API int Base64_Decode(const byte* in, word32 inLen, byte* out,
\sa Base64_Decode
\sa Base16_Encode
*/
WOLFSSL_API
int Base16_Decode(const byte* in, word32 inLen, byte* out, word32* outLen);
WOLFSSL_API
int Base16_Decode(const byte* in, word32 inLen, byte* out, word32* outLen);
/*!
\ingroup Base_Encoding
@ -224,5 +224,5 @@ WOLFSSL_API int Base64_Decode(const byte* in, word32 inLen, byte* out,
\sa Base64_Decode
\sa Base16_Decode
*/
WOLFSSL_API
int Base16_Encode(const byte* in, word32 inLen, byte* out, word32* outLen);
WOLFSSL_API
int Base16_Encode(const byte* in, word32 inLen, byte* out, word32* outLen);

View File

@ -86,7 +86,7 @@ int wc_ecc_make_key(WC_RNG* rng, int keysize, ecc_key* key);
\sa wc_ecc_point_is_at_infinity
*/
WOLFSSL_API
int wc_ecc_make_pub(ecc_key* key, ecc_point* pubOut);
int wc_ecc_check_key(ecc_key* key);
/*!
\ingroup ECC
@ -195,7 +195,7 @@ int wc_ecc_shared_secret(ecc_key* private_key, ecc_key* public_key, byte* out,
point = wc_ecc_new_point();
result = wc_ecc_shared_secret_ssh(&key, point,
result = wc_ecc_shared_secret_ex(&key, point,
&shared_secret, &secret_size);
if (result != MP_OKAY)
@ -1334,7 +1334,7 @@ int wc_ecc_size(ecc_key* key);
_Example_
\code
int sigSz = wc_ecc_sig_size(32);
int sigSz = wc_ecc_sig_size_calc(32);
if ( sigSz == 0) {
// error determining sig size
}

View File

@ -36,7 +36,7 @@ WOLFSSL_API const WOLFSSL_EVP_CIPHER* wolfSSL_EVP_des_ede3_ecb(void);
_Example_
\code
WOLFSSL_EVP_CIPHER* cipher;
cipher = wolfSSL_EVP_des_ecb();
cipher = wolfSSL_EVP_des_cbc();
\endcode

View File

@ -24,7 +24,7 @@
\sa XFREE
\sa XREALLOC
*/
WOLFSSL_API void* wolfSSL_Malloc(size_t size, void* heap, int type, const char* func, unsigned int line);
WOLFSSL_API void* wolfSSL_Malloc(size_t size, void* heap, int type, const char* func, unsigned int line);
/*!
\ingroup Memory
@ -54,7 +54,7 @@
\sa XFREE
\sa XREALLOC
*/
WOLFSSL_API void wolfSSL_Free(void *ptr, void* heap, int type, const char* func, unsigned int line);
WOLFSSL_API void wolfSSL_Free(void *ptr, void* heap, int type, const char* func, unsigned int line);
/*!
\ingroup Memory
@ -83,7 +83,7 @@
\sa XFREE
\sa XREALLOC
*/
WOLFSSL_API void* wolfSSL_Realloc(void *ptr, size_t size, void* heap, int type, const char* func, unsigned int line);
WOLFSSL_API void* wolfSSL_Realloc(void *ptr, size_t size, void* heap, int type, const char* func, unsigned int line);
/*!
\ingroup Memory
@ -113,7 +113,7 @@
\sa wolfSSL_Realloc
\sa wolfSSL_SetAllocators
*/
WOLFSSL_API void* wolfSSL_Malloc(size_t size, void* heap, int type);
WOLFSSL_API void* wolfSSL_Malloc(size_t size, void* heap, int type);
/*!
\ingroup Memory
@ -147,7 +147,7 @@
\sa wolfSSL_Malloc
\sa wolfSSL_SetAllocators
*/
WOLFSSL_API void* wolfSSL_Realloc(void *ptr, size_t size, void* heap, int type);
WOLFSSL_API void* wolfSSL_Realloc(void *ptr, size_t size, void* heap, int type);
/*!
\ingroup Memory
@ -171,7 +171,7 @@
\sa wolfSSL_Realloc
\sa wolfSSL_SetAllocators
*/
WOLFSSL_API void wolfSSL_Free(void *ptr, const char* func, unsigned int line);
WOLFSSL_API void wolfSSL_Free(void *ptr, const char* func, unsigned int line);
/*!
\ingroup Memory
@ -289,4 +289,4 @@ WOLFSSL_API int wolfSSL_SetAllocators(wolfSSL_Malloc_cb,
\sa wolfSSL_Malloc
\sa wolfSSL_Free
*/
WOLFSSL_API int wolfSSL_MemoryPaddingSz(void);
WOLFSSL_API int wolfSSL_MemoryPaddingSz(void);

View File

@ -111,7 +111,7 @@ WOLFSSL_API void wc_PKCS7_Free(PKCS7* pkcs7);
pkcs7.contentSz = dataSz;
... etc.
ret = wc_PKCS7_EnocodeData(&pkcs7, pkcs7Buff, sizeof(pkcs7Buff));
ret = wc_PKCS7_EncodeData(&pkcs7, pkcs7Buff, sizeof(pkcs7Buff));
if ( ret != 0 ) {
// error encoding into output buffer
}
@ -182,7 +182,7 @@ WOLFSSL_API int wc_PKCS7_EncodeData(PKCS7* pkcs7, byte* output,
pkcs7.contentSz = dataSz;
... etc.
ret = wc_PKCS7_EnocodeSignedData(&pkcs7, pkcs7Buff, sizeof(pkcs7Buff));
ret = wc_PKCS7_EncodeSignedData(&pkcs7, pkcs7Buff, sizeof(pkcs7Buff));
if ( ret != 0 ) {
// error encoding into output buffer
}
@ -258,7 +258,7 @@ WOLFSSL_API int wc_PKCS7_EncodeSignedData(PKCS7* pkcs7,
pkcs7.contentSz = dataSz;
... etc.
ret = wc_PKCS7_EnocodeSignedData(&pkcs7, pkcs7Buff, sizeof(pkcs7Buff));
ret = wc_PKCS7_EncodeSignedData(&pkcs7, pkcs7Buff, sizeof(pkcs7Buff));
if ( ret != 0 ) {
// error encoding into output buffer
}

View File

@ -24,7 +24,7 @@
\sa wc_FreeNetRandom
*/
WOLFSSL_API int wc_InitNetRandom(const char*, wnr_hmac_key, int);
WOLFSSL_API int wc_InitNetRandom(const char*, wnr_hmac_key, int);
/*!
\ingroup Random
@ -46,7 +46,7 @@
\sa wc_InitNetRandom
*/
WOLFSSL_API int wc_FreeNetRandom(void);
WOLFSSL_API int wc_FreeNetRandom(void);
/*!
\ingroup Random
@ -254,7 +254,7 @@ WOLFSSL_API int wc_FreeRng(WC_RNG*);
\sa wc_RNG_GenerateByte
\sa wc_FreeRng
*/
WOLFSSL_API int wc_RNG_HealthTest(int reseed,
WOLFSSL_API int wc_RNG_HealthTest(int reseed,
const byte* entropyA, word32 entropyASz,
const byte* entropyB, word32 entropyBSz,
byte* output, word32 outputSz);

View File

@ -18,7 +18,7 @@
\code
RsaKey enc;
int ret;
ret = wc_RsaInitKey(&enc, NULL); // not using heap hint. No custom memory
ret = wc_InitRsaKey(&enc, NULL); // not using heap hint. No custom memory
if ( ret != 0 ) {
// error initializing RSA key
}

View File

@ -227,8 +227,8 @@ WOLFSSL_API int wc_Sha224Update(wc_Sha224*, const byte*, word32);
WOLFSSL_MSG("wc_InitSha224 failed");
}
else {
wc_Sha256Update(&sha224, data, len);
wc_Sha256Final(&sha224, hash);
wc_Sha224Update(&sha224, data, len);
wc_Sha224Final(&sha224, hash);
}
\endcode

View File

@ -2179,7 +2179,7 @@ WOLFSSL_API int wolfSSL_get_alert_history(WOLFSSL*, WOLFSSL_ALERT_HISTORY *);
\sa wolfSSL_get_session
*/
WOLFSSL_API int wolfSSL_set_session(WOLFSSL* ssl,WOLFSSL_SESSION* session);
WOLFSSL_API int wolfSSL_set_session(WOLFSSL*, WOLFSSL_SESSION*);
/*!
\ingroup IO
@ -2217,7 +2217,7 @@ WOLFSSL_API int wolfSSL_set_session(WOLFSSL* ssl,WOLFSSL_SESSION* session
\sa wolfSSL_set_session
*/
WOLFSSL_API WOLFSSL_SESSION* wolfSSL_get_session(WOLFSSL* ssl);
WOLFSSL_API WOLFSSL_SESSION* wolfSSL_get_session(WOLFSSL*);
/*!
\ingroup IO
@ -2244,7 +2244,7 @@ WOLFSSL_API WOLFSSL_SESSION* wolfSSL_get_session(WOLFSSL* ssl);
\sa wolfSSL_get_session
\sa wolfSSL_set_session
*/
WOLFSSL_API void wolfSSL_flush_sessions(WOLFSSL_CTX *ctx, long tm);
WOLFSSL_API void wolfSSL_flush_sessions(WOLFSSL_CTX*, long);
/*!
\ingroup TLS
@ -2279,7 +2279,7 @@ WOLFSSL_API void wolfSSL_flush_sessions(WOLFSSL_CTX *ctx, long tm);
\sa GetSessionClient
*/
WOLFSSL_API int wolfSSL_SetServerID(WOLFSSL* ssl, const unsigned char*,
WOLFSSL_API int wolfSSL_SetServerID(WOLFSSL*, const unsigned char*,
int, int);
/*!
\ingroup IO

View File

@ -295,7 +295,7 @@ WOLFSSL_API void wolfSSL_SetIOReadCtx( WOLFSSL* ssl, void *ctx);
WOLFSSL* ssl = 0;
...
// Manually setting the socket fd as the send CTX, for example
wolfSSL_SetIOSendCtx(ssl, &sockfd);
wolfSSL_SetIOWriteCtx(ssl, &sockfd);
...
\endcode
@ -427,7 +427,7 @@ WOLFSSL_API void wolfSSL_SetIOReadFlags( WOLFSSL* ssl, int flags);
WOLFSSL* ssl = 0;
...
// Manually setting send flags to 0
wolfSSL_SetIOSendFlags(ssl, 0);
wolfSSL_SetIOWriteFlags(ssl, 0);
...
\endcode