1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/security/nss/lib/cryptohi/cryptohi.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,368 @@
1.4 +/*
1.5 + * cryptohi.h - public prototypes for the crypto library
1.6 + *
1.7 + * This Source Code Form is subject to the terms of the Mozilla Public
1.8 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.9 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.10 +
1.11 +#ifndef _CRYPTOHI_H_
1.12 +#define _CRYPTOHI_H_
1.13 +
1.14 +#include "blapit.h"
1.15 +
1.16 +#include "seccomon.h"
1.17 +#include "secoidt.h"
1.18 +#include "secdert.h"
1.19 +#include "cryptoht.h"
1.20 +#include "keyt.h"
1.21 +#include "certt.h"
1.22 +
1.23 +
1.24 +SEC_BEGIN_PROTOS
1.25 +
1.26 +
1.27 +/****************************************/
1.28 +/*
1.29 +** DER encode/decode (EC)DSA signatures
1.30 +*/
1.31 +
1.32 +/* ANSI X9.57 defines DSA signatures as DER encoded data. Our DSA1 code (and
1.33 + * most of the rest of the world) just generates 40 bytes of raw data. These
1.34 + * functions convert between formats.
1.35 + */
1.36 +extern SECStatus DSAU_EncodeDerSig(SECItem *dest, SECItem *src);
1.37 +extern SECItem *DSAU_DecodeDerSig(const SECItem *item);
1.38 +
1.39 +/*
1.40 + * Unlike DSA1, raw DSA2 and ECDSA signatures do not have a fixed length.
1.41 + * Rather they contain two integers r and s whose length depends
1.42 + * on the size of q or the EC key used for signing.
1.43 + *
1.44 + * We can reuse the DSAU_EncodeDerSig interface to DER encode
1.45 + * raw ECDSA signature keeping in mind that the length of r
1.46 + * is the same as that of s and exactly half of src->len.
1.47 + *
1.48 + * For decoding, we need to pass the length of the desired
1.49 + * raw signature (twice the key size) explicitly.
1.50 + */
1.51 +extern SECStatus DSAU_EncodeDerSigWithLen(SECItem *dest, SECItem *src,
1.52 + unsigned int len);
1.53 +extern SECItem *DSAU_DecodeDerSigToLen(const SECItem *item, unsigned int len);
1.54 +
1.55 +/****************************************/
1.56 +/*
1.57 +** Signature creation operations
1.58 +*/
1.59 +
1.60 +/*
1.61 +** Create a new signature context used for signing a data stream.
1.62 +** "alg" the signature algorithm to use (e.g. SEC_OID_PKCS1_MD5_WITH_RSA_ENCRYPTION)
1.63 +** "privKey" the private key to use
1.64 +*/
1.65 +extern SGNContext *SGN_NewContext(SECOidTag alg, SECKEYPrivateKey *privKey);
1.66 +
1.67 +/*
1.68 +** Destroy a signature-context object
1.69 +** "cx" the object
1.70 +** "freeit" if PR_TRUE then free the object as well as its sub-objects
1.71 +*/
1.72 +extern void SGN_DestroyContext(SGNContext *cx, PRBool freeit);
1.73 +
1.74 +/*
1.75 +** Reset the signing context "cx" to its initial state, preparing it for
1.76 +** another stream of data.
1.77 +*/
1.78 +extern SECStatus SGN_Begin(SGNContext *cx);
1.79 +
1.80 +/*
1.81 +** Update the signing context with more data to sign.
1.82 +** "cx" the context
1.83 +** "input" the input data to sign
1.84 +** "inputLen" the length of the input data
1.85 +*/
1.86 +extern SECStatus SGN_Update(SGNContext *cx, const unsigned char *input,
1.87 + unsigned int inputLen);
1.88 +
1.89 +/*
1.90 +** Finish the signature process. Use either k0 or k1 to sign the data
1.91 +** stream that was input using SGN_Update. The resulting signature is
1.92 +** formatted using PKCS#1 and then encrypted using RSA private or public
1.93 +** encryption.
1.94 +** "cx" the context
1.95 +** "result" the final signature data (memory is allocated)
1.96 +*/
1.97 +extern SECStatus SGN_End(SGNContext *cx, SECItem *result);
1.98 +
1.99 +/*
1.100 +** Sign a single block of data using private key encryption and given
1.101 +** signature/hash algorithm.
1.102 +** "result" the final signature data (memory is allocated)
1.103 +** "buf" the input data to sign
1.104 +** "len" the amount of data to sign
1.105 +** "pk" the private key to encrypt with
1.106 +** "algid" the signature/hash algorithm to sign with
1.107 +** (must be compatible with the key type).
1.108 +*/
1.109 +extern SECStatus SEC_SignData(SECItem *result,
1.110 + const unsigned char *buf, int len,
1.111 + SECKEYPrivateKey *pk, SECOidTag algid);
1.112 +
1.113 +/*
1.114 +** Sign a pre-digested block of data using private key encryption, encoding
1.115 +** The given signature/hash algorithm.
1.116 +** "result" the final signature data (memory is allocated)
1.117 +** "digest" the digest to sign
1.118 +** "privKey" the private key to encrypt with
1.119 +** "algtag" The algorithm tag to encode (need for RSA only)
1.120 +*/
1.121 +extern SECStatus SGN_Digest(SECKEYPrivateKey *privKey,
1.122 + SECOidTag algtag, SECItem *result, SECItem *digest);
1.123 +
1.124 +/*
1.125 +** DER sign a single block of data using private key encryption and the
1.126 +** MD5 hashing algorithm. This routine first computes a digital signature
1.127 +** using SEC_SignData, then wraps it with an CERTSignedData and then der
1.128 +** encodes the result.
1.129 +** "arena" is the memory arena to use to allocate data from
1.130 +** "result" the final der encoded data (memory is allocated)
1.131 +** "buf" the input data to sign
1.132 +** "len" the amount of data to sign
1.133 +** "pk" the private key to encrypt with
1.134 +*/
1.135 +extern SECStatus SEC_DerSignData(PLArenaPool *arena, SECItem *result,
1.136 + const unsigned char *buf, int len,
1.137 + SECKEYPrivateKey *pk, SECOidTag algid);
1.138 +
1.139 +/*
1.140 +** Destroy a signed-data object.
1.141 +** "sd" the object
1.142 +** "freeit" if PR_TRUE then free the object as well as its sub-objects
1.143 +*/
1.144 +extern void SEC_DestroySignedData(CERTSignedData *sd, PRBool freeit);
1.145 +
1.146 +/*
1.147 +** Get the signature algorithm tag number for the given key type and hash
1.148 +** algorithm tag. Returns SEC_OID_UNKNOWN if key type and hash algorithm
1.149 +** do not match or are not supported.
1.150 +*/
1.151 +extern SECOidTag SEC_GetSignatureAlgorithmOidTag(KeyType keyType,
1.152 + SECOidTag hashAlgTag);
1.153 +
1.154 +/****************************************/
1.155 +/*
1.156 +** Signature verification operations
1.157 +*/
1.158 +
1.159 +/*
1.160 +** Create a signature verification context. This version is deprecated,
1.161 +** This function is deprecated. Use VFY_CreateContextDirect or
1.162 +** VFY_CreateContextWithAlgorithmID instead.
1.163 +** "key" the public key to verify with
1.164 +** "sig" the encrypted signature data if sig is NULL then
1.165 +** VFY_EndWithSignature must be called with the correct signature at
1.166 +** the end of the processing.
1.167 +** "sigAlg" specifies the signing algorithm to use (including the
1.168 +** hash algorthim). This must match the key type.
1.169 +** "wincx" void pointer to the window context
1.170 +*/
1.171 +extern VFYContext *VFY_CreateContext(SECKEYPublicKey *key, SECItem *sig,
1.172 + SECOidTag sigAlg, void *wincx);
1.173 +/*
1.174 +** Create a signature verification context.
1.175 +** "key" the public key to verify with
1.176 +** "sig" the encrypted signature data if sig is NULL then
1.177 +** VFY_EndWithSignature must be called with the correct signature at
1.178 +** the end of the processing.
1.179 +** "pubkAlg" specifies the cryptographic signing algorithm to use (the
1.180 +** raw algorithm without any hash specified. This must match the key
1.181 +** type.
1.182 +** "hashAlg" specifies the hashing algorithm used. If the key is an
1.183 +** RSA key, and sig is not NULL, then hashAlg can be SEC_OID_UNKNOWN.
1.184 +** the hash is selected from data in the sig.
1.185 +** "hash" optional pointer to return the actual hash algorithm used.
1.186 +** in practice this should always match the passed in hashAlg (the
1.187 +** exception is the case where hashAlg is SEC_OID_UNKNOWN above).
1.188 +** If this value is NULL no, hash oid is returned.
1.189 +** "wincx" void pointer to the window context
1.190 +*/
1.191 +extern VFYContext *VFY_CreateContextDirect(const SECKEYPublicKey *key,
1.192 + const SECItem *sig,
1.193 + SECOidTag pubkAlg,
1.194 + SECOidTag hashAlg,
1.195 + SECOidTag *hash, void *wincx);
1.196 +/*
1.197 +** Create a signature verification context from a algorithm ID.
1.198 +** "key" the public key to verify with
1.199 +** "sig" the encrypted signature data if sig is NULL then
1.200 +** VFY_EndWithSignature must be called with the correct signature at
1.201 +** the end of the processing.
1.202 +** "algid" specifies the signing algorithm and parameters to use.
1.203 +** This must match the key type.
1.204 +** "hash" optional pointer to return the oid of the actual hash used in
1.205 +** the signature. If this value is NULL no, hash oid is returned.
1.206 +** "wincx" void pointer to the window context
1.207 +*/
1.208 +extern VFYContext *VFY_CreateContextWithAlgorithmID(const SECKEYPublicKey *key,
1.209 + const SECItem *sig,
1.210 + const SECAlgorithmID *algid,
1.211 + SECOidTag *hash,
1.212 + void *wincx);
1.213 +
1.214 +/*
1.215 +** Destroy a verification-context object.
1.216 +** "cx" the context to destroy
1.217 +** "freeit" if PR_TRUE then free the object as well as its sub-objects
1.218 +*/
1.219 +extern void VFY_DestroyContext(VFYContext *cx, PRBool freeit);
1.220 +
1.221 +extern SECStatus VFY_Begin(VFYContext *cx);
1.222 +
1.223 +/*
1.224 +** Update a verification context with more input data. The input data
1.225 +** is fed to a secure hash function (depending on what was in the
1.226 +** encrypted signature data).
1.227 +** "cx" the context
1.228 +** "input" the input data
1.229 +** "inputLen" the amount of input data
1.230 +*/
1.231 +extern SECStatus VFY_Update(VFYContext *cx, const unsigned char *input,
1.232 + unsigned int inputLen);
1.233 +
1.234 +/*
1.235 +** Finish the verification process. The return value is a status which
1.236 +** indicates success or failure. On success, the SECSuccess value is
1.237 +** returned. Otherwise, SECFailure is returned and the error code found
1.238 +** using PORT_GetError() indicates what failure occurred.
1.239 +** "cx" the context
1.240 +*/
1.241 +extern SECStatus VFY_End(VFYContext *cx);
1.242 +
1.243 +/*
1.244 +** Finish the verification process. The return value is a status which
1.245 +** indicates success or failure. On success, the SECSuccess value is
1.246 +** returned. Otherwise, SECFailure is returned and the error code found
1.247 +** using PORT_GetError() indicates what failure occurred. If signature is
1.248 +** supplied the verification uses this signature to verify, otherwise the
1.249 +** signature passed in VFY_CreateContext() is used.
1.250 +** VFY_EndWithSignature(cx,NULL); is identical to VFY_End(cx);.
1.251 +** "cx" the context
1.252 +** "sig" the encrypted signature data
1.253 +*/
1.254 +extern SECStatus VFY_EndWithSignature(VFYContext *cx, SECItem *sig);
1.255 +
1.256 +
1.257 +/*
1.258 +** Verify the signature on a block of data for which we already have
1.259 +** the digest. The signature data is an RSA private key encrypted
1.260 +** block of data formatted according to PKCS#1.
1.261 +** This function is deprecated. Use VFY_VerifyDigestDirect or
1.262 +** VFY_VerifyDigestWithAlgorithmID instead.
1.263 +** "dig" the digest
1.264 +** "key" the public key to check the signature with
1.265 +** "sig" the encrypted signature data
1.266 +** "sigAlg" specifies the signing algorithm to use. This must match
1.267 +** the key type.
1.268 +** "wincx" void pointer to the window context
1.269 +**/
1.270 +extern SECStatus VFY_VerifyDigest(SECItem *dig, SECKEYPublicKey *key,
1.271 + SECItem *sig, SECOidTag sigAlg, void *wincx);
1.272 +/*
1.273 +** Verify the signature on a block of data for which we already have
1.274 +** the digest. The signature data is an RSA private key encrypted
1.275 +** block of data formatted according to PKCS#1.
1.276 +** "dig" the digest
1.277 +** "key" the public key to check the signature with
1.278 +** "sig" the encrypted signature data
1.279 +** "pubkAlg" specifies the cryptographic signing algorithm to use (the
1.280 +** raw algorithm without any hash specified. This must match the key
1.281 +** type.
1.282 +** "hashAlg" specifies the hashing algorithm used.
1.283 +** "wincx" void pointer to the window context
1.284 +**/
1.285 +extern SECStatus VFY_VerifyDigestDirect(const SECItem *dig,
1.286 + const SECKEYPublicKey *key,
1.287 + const SECItem *sig, SECOidTag pubkAlg,
1.288 + SECOidTag hashAlg, void *wincx);
1.289 +/*
1.290 +** Verify the signature on a block of data for which we already have
1.291 +** the digest. The signature data is an RSA private key encrypted
1.292 +** block of data formatted according to PKCS#1.
1.293 +** "key" the public key to verify with
1.294 +** "sig" the encrypted signature data if sig is NULL then
1.295 +** VFY_EndWithSignature must be called with the correct signature at
1.296 +** the end of the processing.
1.297 +** "algid" specifies the signing algorithm and parameters to use.
1.298 +** This must match the key type.
1.299 +** "hash" oid of the actual hash used to create digest. If this value is
1.300 +** not set to SEC_OID_UNKNOWN, it must match the hash of the signature.
1.301 +** "wincx" void pointer to the window context
1.302 +*/
1.303 +extern SECStatus VFY_VerifyDigestWithAlgorithmID(const SECItem *dig,
1.304 + const SECKEYPublicKey *key, const SECItem *sig,
1.305 + const SECAlgorithmID *algid, SECOidTag hash,
1.306 + void *wincx);
1.307 +
1.308 +/*
1.309 +** Verify the signature on a block of data. The signature data is an RSA
1.310 +** private key encrypted block of data formatted according to PKCS#1.
1.311 +** This function is deprecated. Use VFY_VerifyDataDirect or
1.312 +** VFY_VerifyDataWithAlgorithmID instead.
1.313 +** "buf" the input data
1.314 +** "len" the length of the input data
1.315 +** "key" the public key to check the signature with
1.316 +** "sig" the encrypted signature data
1.317 +** "sigAlg" specifies the signing algorithm to use. This must match
1.318 +** the key type.
1.319 +** "wincx" void pointer to the window context
1.320 +*/
1.321 +extern SECStatus VFY_VerifyData(const unsigned char *buf, int len,
1.322 + const SECKEYPublicKey *key, const SECItem *sig,
1.323 + SECOidTag sigAlg, void *wincx);
1.324 +/*
1.325 +** Verify the signature on a block of data. The signature data is an RSA
1.326 +** private key encrypted block of data formatted according to PKCS#1.
1.327 +** "buf" the input data
1.328 +** "len" the length of the input data
1.329 +** "key" the public key to check the signature with
1.330 +** "sig" the encrypted signature data
1.331 +** "pubkAlg" specifies the cryptographic signing algorithm to use (the
1.332 +** raw algorithm without any hash specified. This must match the key
1.333 +** type.
1.334 +** "hashAlg" specifies the hashing algorithm used. If the key is an
1.335 +** RSA key, and sig is not NULL, then hashAlg can be SEC_OID_UNKNOWN.
1.336 +** the hash is selected from data in the sig.
1.337 +** "hash" optional pointer to return the actual hash algorithm used.
1.338 +** in practice this should always match the passed in hashAlg (the
1.339 +** exception is the case where hashAlg is SEC_OID_UNKNOWN above).
1.340 +** If this value is NULL no, hash oid is returned.
1.341 +** "wincx" void pointer to the window context
1.342 +*/
1.343 +extern SECStatus VFY_VerifyDataDirect(const unsigned char *buf, int len,
1.344 + const SECKEYPublicKey *key,
1.345 + const SECItem *sig,
1.346 + SECOidTag pubkAlg, SECOidTag hashAlg,
1.347 + SECOidTag *hash, void *wincx);
1.348 +
1.349 +/*
1.350 +** Verify the signature on a block of data. The signature data is an RSA
1.351 +** private key encrypted block of data formatted according to PKCS#1.
1.352 +** "buf" the input data
1.353 +** "len" the length of the input data
1.354 +** "key" the public key to check the signature with
1.355 +** "sig" the encrypted signature data
1.356 +** "algid" specifies the signing algorithm and parameters to use.
1.357 +** This must match the key type.
1.358 +** "hash" optional pointer to return the oid of the actual hash used in
1.359 +** the signature. If this value is NULL no, hash oid is returned.
1.360 +** "wincx" void pointer to the window context
1.361 +*/
1.362 +extern SECStatus VFY_VerifyDataWithAlgorithmID(const unsigned char *buf,
1.363 + int len, const SECKEYPublicKey *key,
1.364 + const SECItem *sig,
1.365 + const SECAlgorithmID *algid, SECOidTag *hash,
1.366 + void *wincx);
1.367 +
1.368 +
1.369 +SEC_END_PROTOS
1.370 +
1.371 +#endif /* _CRYPTOHI_H_ */
