fix pk7_doit.c for new i2d_ASN1_SET argument
[openssl.git] / doc / envelope.doc
1 The following routines are use to create 'digital' envelopes.
2 By this I mean that they perform various 'higher' level cryptographic
3 functions.  Have a read of 'cipher.doc' and 'digest.doc' since those
4 routines are used by these functions.
5 cipher.doc contains documentation about the cipher part of the
6 envelope library and digest.doc contatins the description of the
7 message digests supported.
8
9 To 'sign' a document involves generating a message digest and then encrypting
10 the digest with an private key.
11
12 #define EVP_SignInit(a,b)               EVP_DigestInit(a,b)
13 #define EVP_SignUpdate(a,b,c)           EVP_DigestUpdate(a,b,c)
14 Due to the fact this operation is basically just an extended message
15 digest, the first 2 functions are macro calls to Digest generating
16 functions.
17
18 int     EVP_SignFinal(
19 EVP_MD_CTX *ctx,
20 unsigned char *md,
21 unsigned int *s,
22 EVP_PKEY *pkey);
23         This finalisation function finishes the generation of the message
24 digest and then encrypts the digest (with the correct message digest 
25 object identifier) with the EVP_PKEY private key.  'ctx' is the message digest
26 context.  'md' will end up containing the encrypted message digest.  This
27 array needs to be EVP_PKEY_size(pkey) bytes long.  's' will actually
28 contain the exact length.  'pkey' of course is the private key.  It is
29 one of EVP_PKEY_RSA or EVP_PKEY_DSA type.
30 If there is an error, 0 is returned, otherwise 1.
31                 
32 Verify is used to check an signed message digest.
33
34 #define EVP_VerifyInit(a,b)             EVP_DigestInit(a,b)
35 #define EVP_VerifyUpdate(a,b,c)         EVP_DigestUpdate(a,b,c)
36 Since the first step is to generate a message digest, the first 2 functions
37 are macros.
38
39 int EVP_VerifyFinal(
40 EVP_MD_CTX *ctx,
41 unsigned char *md,
42 unsigned int s,
43 EVP_PKEY *pkey);
44         This function finishes the generation of the message digest and then
45 compares it with the supplied encrypted message digest.  'md' contains the
46 's' bytes of encrypted message digest.  'pkey' is used to public key decrypt
47 the digest.  It is then compared with the message digest just generated.
48 If they match, 1 is returned else 0.
49
50 int     EVP_SealInit(EVP_CIPHER_CTX *ctx, EVP_CIPHER *type, unsigned char **ek,
51                 int *ekl, unsigned char *iv, EVP_PKEY **pubk, int npubk);
52 Must have at least one public key, error is 0.  I should also mention that
53 the buffers pointed to by 'ek' need to be EVP_PKEY_size(pubk[n]) is size.
54
55 #define EVP_SealUpdate(a,b,c,d,e)       EVP_EncryptUpdate(a,b,c,d,e)    
56 void    EVP_SealFinal(EVP_CIPHER_CTX *ctx,unsigned char *out,int *outl);
57
58
59 int     EVP_OpenInit(EVP_CIPHER_CTX *ctx,EVP_CIPHER *type,unsigned char *ek,
60                 int ekl,unsigned char *iv,EVP_PKEY *priv);
61 0 on failure
62
63 #define EVP_OpenUpdate(a,b,c,d,e)       EVP_DecryptUpdate(a,b,c,d,e)
64
65 int     EVP_OpenFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl);
66 Decrypt final return code
67