aboutsummaryrefslogtreecommitdiffstats
path: root/lib/public_key/doc/src/public_key.xml
diff options
context:
space:
mode:
authorIngela Anderton Andin <[email protected]>2010-07-05 17:24:40 +0200
committerIngela Anderton Andin <[email protected]>2010-08-23 12:09:41 +0200
commit12dfe961aeaf1a826d851361a24519e54d8ef119 (patch)
tree8bf30474bdf6f7aa0cafbcc27a8f2694cc05b141 /lib/public_key/doc/src/public_key.xml
parent871fdb232d7facc58c202ef81634a12fbdcfefb4 (diff)
downloadotp-12dfe961aeaf1a826d851361a24519e54d8ef119.tar.gz
otp-12dfe961aeaf1a826d851361a24519e54d8ef119.tar.bz2
otp-12dfe961aeaf1a826d851361a24519e54d8ef119.zip
Revise the public_key API
Cleaned up and documented the public_key API to make it useful for general use.
Diffstat (limited to 'lib/public_key/doc/src/public_key.xml')
-rw-r--r--lib/public_key/doc/src/public_key.xml500
1 files changed, 300 insertions, 200 deletions
diff --git a/lib/public_key/doc/src/public_key.xml b/lib/public_key/doc/src/public_key.xml
index dc9a96906f..c72719fac4 100644
--- a/lib/public_key/doc/src/public_key.xml
+++ b/lib/public_key/doc/src/public_key.xml
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="iso-8859-1" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">
<erlref>
@@ -34,11 +34,7 @@
<modulesummary> API module for public key infrastructure.</modulesummary>
<description>
<p>This module provides functions to handle public key infrastructure
- from RFC 3280 - X.509 certificates (will later be upgraded to RFC 5280)
- and some parts of the PKCS-standard.
- Currently this application is mainly used by the new
- ssl implementation. The API is yet under construction
- and only a few of the functions are currently documented and thereby supported.
+ from RFC 5280 - X.509 certificates and some parts of the PKCS-standard.
</p>
</description>
@@ -62,37 +58,37 @@
<p><c>boolean() = true | false</c></p>
- <p><c>string = [bytes()]</c></p>
-
- <p><c>asn1_der_encoded() = binary() | [bytes()]</c></p>
+ <p><c>string = [bytes()]</c></p>
+
+ <p><c>der_encoded() = binary() </c></p>
- <p><c>der_bin() = binary() </c></p>
+ <p><c>decrypt_der() = binary() </c></p>
- <p><c>oid() - a tuple of integers
- as generated by the asn1 compiler.</c></p>
-
- <p><c>public_key() = rsa_public_key() | dsa_public_key()</c></p>
+ <p><c>pki_asn1_type() = 'Certificate' | 'RSAPrivateKey'|
+ 'DSAPrivateKey' | 'DHParameter'</c></p>
+ <p><c>pem_entry () = {pki_asn1_type(), der_encoded() | decrypt_der(), not_encrypted |
+ {"DES-CBC" | "DES-EDE3-CBC", crypto:rand_bytes(8)}}.</c></p>
+
<p><c>rsa_public_key() = #'RSAPublicKey'{}</c></p>
<p><c>rsa_private_key() = #'RSAPrivateKey'{} </c></p>
- <p><c>dsa_public_key() = integer() </c></p>
-
- <p><c>public_key_params() = dsa_key_params() </c></p>
-
- <p><c>dsa_key_params() = #'Dss-Parms'{} </c></p>
-
- <p><c>private_key() = rsa_private_key() | dsa_private_key()</c></p>
+ <p><c>dsa_public_key() = {integer(), #'Dss-Parms'{}} </c></p>
<p><c>rsa_private_key() = #'RSAPrivateKey'{} </c></p>
<p><c>dsa_private_key() = #'DSAPrivateKey'{}</c></p>
+
+ <p><c> public_crypt_options() = [{rsa_pad, rsa_padding()}]. </c></p>
- <p><c>x509_certificate() = "#Certificate{}"</c></p>
-
- <p><c>x509_tbs_certificate() = #'TBSCertificate'{} </c></p>
-
+ <p><c> rsa_padding() = 'rsa_pkcs1_padding' | 'rsa_pkcs1_oaep_padding'
+ | 'rsa_no_padding'</c></p>
+
+ <p><c> rsa_digest_type() = 'md5' | 'sha' </c></p>
+
+ <p><c> dss_digest_type() = 'none' | 'sha' </c></p>
+
<!-- <p><c>policy_tree() = [Root, Children]</c></p> -->
<!-- <p><c>Root = #policy_tree_node{}</c></p> -->
@@ -121,197 +117,301 @@
<!-- that would satisfy this policy in the certificate x+1. </item> -->
<!-- </taglist> -->
</section>
-
-<funcs>
- <func>
- <name>decode_private_key(KeyInfo) -> </name>
- <name>decode_private_key(KeyInfo, Password) -> {ok, PrivateKey} | {error, Reason}</name>
- <fsummary> Decodes an asn1 der encoded private key.</fsummary>
- <type>
- <v> KeyInfo = {KeyType, der_bin(), ChipherInfo} </v>
- <d> As returned from pem_to_der/1 for private keys</d>
- <v> KeyType = rsa_private_key | dsa_private_key </v>
- <v> ChipherInfo = opaque() | no_encryption </v>
- <d> ChipherInfo may contain encryption parameters if the private key is password
- protected, these are opaque to the user just pass the value returned by pem_to_der/1
- to this function.</d>
- <v> Password = string() </v>
- <d>Must be specified if CipherInfo =/= no_encryption</d>
- <v> PrivateKey = private_key() </v>
- <v> Reason = term() </v>
- </type>
- <desc>
- <p>Decodes an asn1 der encoded private key.</p>
- </desc>
- </func>
-
+
+<funcs>
+
<func>
- <name>pem_to_der(File) -> {ok, [Entry]}</name>
- <fsummary>Reads a PEM file and translates it into its asn1 der
- encoded parts.</fsummary>
+ <name>decrypt_private(CipherText, Key [, Options]) -> binary()</name>
+ <fsummary>Public key decryption.</fsummary>
<type>
- <v>File = path()</v>
- <v>Password = string()</v>
- <v>Entry = {entry_type(), der_bin(), CipherInfo}</v>
- <v> ChipherInfo = opaque() | no_encryption </v>
- <d> ChipherInfo may contain encryption parameters if the private key is password
- protected, these will be handled by the function decode_private_key/2. </d>
- <v>entry_type() = cert | cert_req | rsa_private_key | dsa_private_key |
- dh_params </v>
+ <v>CipherText = binary()</v>
+ <v>Key = rsa_private_key()</v>
+ <v>Options = public_crypt_options()</v>
</type>
<desc>
- <p>Reads a PEM file and translates it into its asn1 der
- encoded parts.</p>
+ <p>Public key decryption using the private key.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>decrypt_public(CipherText, Key [, Options]) - > binary()</name>
+ <fsummary></fsummary>
+ <type>
+ <v>CipherText = binary()</v>
+ <v>Key = rsa_public_key()</v>
+ <v>Options = public_crypt_options()</v>
+ </type>
+ <desc>
+ <p> Public key decryption using the public key.</p>
</desc>
</func>
-
- <func>
- <name>pkix_decode_cert(Cert, Type) -> {ok, DecodedCert} | {error, Reason}</name>
- <fsummary> Decodes an asn1 der encoded pkix certificate. </fsummary>
- <type>
- <v>Cert = asn1_der_encoded() </v>
- <v>Type = plain | otp</v>
- <v>DecodeCert = x509_certificate() </v>
- <d>When type is specified as otp the asn1 spec OTP-PKIX.asn1 is used to decode known
- extensions and enhance the signature field in
- #'Certificate'{} and '#TBSCertificate'{}. This is currently used by the new ssl
- implementation but not documented and supported for the public_key application.</d>
- <v>Reason = term() </v>
+
+ <func>
+ <name>der_decode(Asn1type, Der) -> term()</name>
+ <fsummary> Decodes a public key asn1 der encoded entity.</fsummary>
+ <type>
+ <v>Asn1Type = atom() -</v>
+ <d> Asn1 type present in the public_key applications
+ asn1 specifications.</d>
+ <v>Der = der_encoded()</v>
</type>
- <desc>
- <p> Decodes an asn1 encoded pkix certificate.</p>
+ <desc>
+ <p> Decodes a public key asn1 der encoded entity.</p>
</desc>
</func>
+
+ <func>
+ <name>der_encode(Asn1Type, Entity) -> der_encoded()</name>
+ <fsummary> Encodes a public key entity with asn1 DER encoding.</fsummary>
+ <type>
+ <v>Asn1Type = atom()</v>
+ <d> Asn1 type present in the public_key applications
+ asn1 specifications.</d>
+ <v>Entity = term() - The erlang representation of <c> Asn1Type</c></v>
+ </type>
+ <desc>
+ <p> Encodes a public key entity with asn1 DER encoding.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>pem_decode(PemBin) -> [pem_entry()]</name>
+ <fsummary>Decode PEM binary data and return
+ entries as asn1 der encoded entities. </fsummary>
+ <type>
+ <v>PemBin = binary()</v>
+ <d>Example {ok, PemBin} = file:read_file("cert.pem").</d>
+ </type>
+ <desc>
+ <p>Decode PEM binary data and return
+ entries as asn1 der encoded entities.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>pem_encode(PemEntries) -> binary()</name>
+ <fsummary>Creates a PEM binary</fsummary>
+ <type>
+ <v> PemEntries = [pem_entry()] </v>
+ </type>
+ <desc>
+ <p>Creates a PEM binary</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>pem_entry_decode(PemEntry [, Password]) -> term()</name>
+ <fsummary>Decodes a pem entry.</fsummary>
+ <type>
+ <v> PemEntry = pem_entry() </v>
+ <v> Password = string() </v>
+ </type>
+ <desc>
+ <p>Decodes a pem entry. pem_decode/1 returns a list of
+ pem entries.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>pem_entry_encode(Asn1Type, Entity [,{CipherInfo, Password}]) -> pem_entry()</name>
+ <fsummary> Creates a pem entry that can be feed to pem_encode/1.</fsummary>
+ <type>
+ <v>Asn1Type = atom()</v>
+ <v>Entity = term()</v>
+ <v>CipherInfo = {"DES-CBC" | "DES-EDE3-CBC", crypto:rand_bytes(8)}</v>
+ <v>Password = string()</v>
+ </type>
+ <desc>
+ <p> Creates a pem entry that can be feed to pem_encode/1.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>encrypt_private(PlainText, Key) -> binary()</name>
+ <fsummary> Public key encryption using the private key.</fsummary>
+ <type>
+ <v>PlainText = binary()</v>
+ <v>Key = rsa_private_key()</v>
+ </type>
+ <desc>
+ <p> Public key encryption using the private key.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>encrypt_public(PlainText, Key) -> binary()</name>
+ <fsummary> Public key encryption using the public key.</fsummary>
+ <type>
+ <v>PlainText = binary()</v>
+ <v>Key = rsa_public_key()</v>
+ </type>
+ <desc>
+ <p> Public key encryption using the public key.</p>
+ </desc>
+ </func>
-<!-- <func> -->
-<!-- <name> pkix_encode_cert(Cert) -> {ok, EncodedCert} | {error, Reason}</name> -->
-<!-- <fsummary>Encodes a certificate record using asn1. </fsummary> -->
-<!-- <type> -->
-<!-- <v>Cert = x509_certificate() </v> -->
-<!-- <v>EncodedCert = asn1_der_encoded() </v> -->
-<!-- <v>Reason = term() </v> -->
-<!-- </type> -->
-<!-- <desc> -->
-<!-- <p> Encodes a certificate record using asn1.</p> -->
-<!-- </desc> -->
-<!-- </func> -->
+ <func>
+ <name> pkix_decode_cert(Cert, otp|plain) -> #'Certificate'{} | #'OTPCertificate'{}</name>
+ <fsummary> Decodes an asn1 der encoded pkix x509 certificate.</fsummary>
+ <type>
+ <v>Cert = der_encoded()</v>
+ </type>
+ <desc>
+ <p>Decodes an asn1 der encoded pkix certificate. The otp option
+ will use the customized asn1 specification OTP-PKIX.asn1 for
+ decoding and also recursively decode most of the standard
+ parts.</p>
+ </desc>
+ </func>
-<!-- <func> -->
-<!-- <name>pkix_path_validation(TrustedCert, CertChain, Options) -> {ok, Result} | {error, Reason}</name> -->
-
-<!-- <fsummary>Performs a basic path validation according to RFC 3280</fsummary> -->
-<!-- <type> -->
-<!-- <v>TrustedCert = asn1_der_encoded()</v> -->
-<!-- <v>CertChain = [asn1_der_encoded()]</v> -->
-<!-- <v>Options = [{Option, Value}]</v> -->
-<!-- <v>Result = {{algorithm(), public_key(), -->
-<!-- public_key_params()}, policy_tree()}</v> -->
-<!-- </type> -->
+ <func>
+ <name>pkix_encode(Asn1Type, Entity, otp | plain) -> der_encoded()</name>
+ <fsummary>Der encodes a pkix x509 certificate or part of such a
+ certificate.</fsummary>
+ <type>
+ <v>Asn1Type = atom()</v>
+ <d>The asn1 type can be 'Certificate', 'OTPCertificate' or a subtype of either .</d>
+ </type>
+ <desc>
+ <p>Der encodes a pkix x509 certificate or part of such a
+ certificate. This function must be used for encoding certificates or parts of certificates
+ that are decoded/created on the otp format, whereas for the plain format this
+ function will directly call der_encode/2. </p>
+ </desc>
+ </func>
+
+ <func>
+ <name>pkix_is_issuer(Cert, IssuerCert) -> boolean()</name>
+ <fsummary> Checks if <c>IssuerCert</c> issued <c>Cert</c> </fsummary>
+ <type>
+ <v>Cert = der_encode() | #'OTPCertificate'{}</v>
+ <v>IssuerCert = der_encode() | #'OTPCertificate'{}</v>
+ </type>
+ <desc>
+ <p> Checks if <c>IssuerCert</c> issued <c>Cert</c> </p>
+ </desc>
+ </func>
+
+ <func>
+ <name>pkix_is_fixed_dh_cert(Cert) -> boolean()</name>
+ <fsummary> Checks if a Certificate is a fixed Diffie-Hellman Cert.</fsummary>
+ <type>
+ <v>Cert = der_encode() | #'OTPCertificate'{}</v>
+ </type>
+ <desc>
+ <p> Checks if a Certificate is a fixed Diffie-Hellman Cert.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>pkix_is_self_signed(Cert) -> boolean()</name>
+ <fsummary> Checks if a Certificate is self signed.</fsummary>
+ <type>
+ <v>Cert = der_encode() | #'OTPCertificate'{}</v>
+ </type>
+ <desc>
+ <p> Checks if a Certificate is self signed.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>pkix_issuer_id(Cert, IssuedBy) -> {ok, IssuerID} | {error, Reason}</name>
+ <fsummary> Returns the issuer id.</fsummary>
+ <type>
+ <v>Cert = der_encode() | #'OTPCertificate'{}</v>
+ <v>IssuedBy = self | other</v>
+ <v>IssuerID = {integer(), {rdnSequence, [#'AttributeTypeAndValue'{}]}}</v>
+ <d>The issuer id consists of the serial number and the issuers name.</d>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p> Returns the issuer id.</p>
+ </desc>
+ </func>
-<!-- <desc> -->
-<!-- <p>Available options are: </p> -->
-<!-- <taglist> -->
-<!-- <tag>{validate_extension_fun, fun()}</tag> -->
-<!-- <item> A fun behaving according to the following outline: -->
-<!-- <code> -->
-<!-- [...] -->
-<!-- ValidateExtensionFun = fun(Extensions, UserState) -> -->
-<!-- validate_extensions(Extensions, UserState, []) -->
-<!-- end, -->
-<!-- [...] -->
+ <func>
+ <name>pkix_normalize_name(Issuer) -> Normalized</name>
+ <fsummary>Normalizes a issuer name so that it can be easily
+ compared to another issuer name. </fsummary>
+ <type>
+ <v>Issuer = {rdnSequence,[#'AttributeTypeAndValue'{}]}</v>
+ <v>Normalized = {rdnSequence, [#'AttributeTypeAndValue'{}]}</v>
+ </type>
+ <desc>
+ <p>Normalizes a issuer name so that it can be easily
+ compared to another issuer name.</p>
+ </desc>
+ </func>
+
+ <!-- <func> -->
+ <!-- <name>pkix_path_validation()</name> -->
+ <!-- <fsummary> Performs a basic path validation according to RFC 5280.</fsummary> -->
+ <!-- <type> -->
+ <!-- <v></v> -->
+ <!-- </type> -->
+ <!-- <desc> -->
+ <!-- <p> Performs a basic path validation according to RFC 5280.</p> -->
+ <!-- </desc> -->
+ <!-- </func> -->
-<!-- validate_extensions([], UserState, UnknowExtension) -> -->
-<!-- {UserState, UnknowExtension}; -->
-<!-- validate_extensions([#'Extension'{} = Ext | Rest], UserState, UnknowExtension) -> -->
-<!-- case valid_extension(Ext) of -->
-<!-- {true, NewUserState} -> -->
-<!-- validate_extensions(Rest, NewUserState, UnknowExtension); -->
-<!-- unknown -> -->
-<!-- validate_extensions(Rest, UserState, [Ext | UnknowExtension]); -->
-<!-- {false, Reason} -> -->
-<!-- throw(bad_cert, Reason) -->
-<!-- end. -->
-<!-- </code> -->
-
-<!-- </item> -->
-
-<!-- <tag>{policy_set, [oid()]}</tag> -->
-<!-- <item>A set of certificate policy -->
-<!-- identifiers naming the policies that are acceptable to the -->
-<!-- certificate user. If the user is not concerned about -->
-<!-- certificate policy there is no need -->
-<!-- to set this option. Defaults to the -->
-<!-- special value [?anyPolicy]. -->
-<!-- </item> -->
-
-<!-- <tag>{policy_mapping, boolean()}</tag> -->
-<!-- <item>Indicates if policy -->
-<!-- mapping, initially, is allowed in the certification path. -->
-<!-- Defaults to false. -->
-<!-- </item> -->
-
-<!-- <tag> {explicit_policy, boolean()}</tag> -->
-<!-- <item>Indicates if the path, initially, must be -->
-<!-- valid for at least one of the certificate policies in the user -->
-<!-- specified policy set. -->
-<!-- Defaults to false. -->
-<!-- </item> -->
+
+ <func>
+ <name>pkix_sign(#'OTPTBSCertificate'{}, Key) -> der_encode()</name>
+ <fsummary>Signs certificate.</fsummary>
+ <type>
+ <v>Key = rsa_public_key() | dsa_public_key()</v>
+ </type>
+ <desc>
+ <p>Signs a 'OTPTBSCertificate'. Returns the corresponding
+ der encoded certificate.</p>
+ </desc>
+ </func>
-<!-- <tag>{inhibit_any_policy, boolean()}</tag> -->
-<!-- <item>Indicates whether the anyPolicy OID, initially, should -->
-<!-- be processed if it is included in a certificate. -->
-<!-- Defaults to false. -->
-<!-- </item> -->
-
-<!-- </taglist> -->
-
-<!-- <p>Performs a basic path validation according to RFC 3280, -->
-<!-- e.i. signature validation, time validation, issuer validation, -->
-<!-- alternative subject name validation, CRL validation, policy -->
-<!-- validation and checks that no unknown extensions -->
-<!-- are marked as critical. The option <c>validate_extension_fun</c> -->
-<!-- may be used to validate application specific extensions. If -->
-<!-- a validation criteria is found to be invalid the validation process -->
-<!-- will immediately be stopped and this functions will return -->
-<!-- {error, Reason}. -->
-<!-- </p> -->
-<!-- </desc> -->
-<!-- </func> -->
+ <func>
+ <name>pkix_verify(Cert, Key) -> boolean()</name>
+ <fsummary> Verify pkix x.509 certificate signature.</fsummary>
+ <type>
+ <v>Cert = der_encode()</v>
+ <v>Key = rsa_public_key() | dsa_public_key()</v>
+ </type>
+ <desc>
+ <p> Verify pkix x.509 certificate signature.</p>
+ </desc>
+ </func>
-<!-- <func> -->
-<!-- <name>sign(DigestOrTBSCert, Key) -> </name> -->
-<!-- <name>sign(DigestOrTBSCert, Key, KeyParams) -> {ok, SignatureOrDerCert} | {error, Reason}</name> -->
-<!-- <fsummary>Signs Digest/Certificate using Key.</fsummary> -->
-<!-- <type> -->
-<!-- <v>DigestOrTBSCert = binary() | x509_tbs_certificate()</v> -->
-<!-- <v>Key = private_key()</v> -->
-<!-- <v>SignatureORDerCert = binary() | der_bin() </v> -->
-<!-- <v>Reason = term() </v> -->
-<!-- </type> -->
-<!-- <desc> -->
-<!-- <p> Signs Digest/Certificate using Key, in the later -->
-<!-- case a der encoded x509_certificate() will be returned. </p> -->
-<!-- </desc> -->
-<!-- </func> -->
+ <func>
+ <name>sign(Msg, DigestType, Key) -> binary()</name>
+ <fsummary> Create digital signature.</fsummary>
+ <type>
+ <v>Msg = binary()</v>
+ <d>The msg is either the binary "plain text" data to be
+ signed or in the case that digest type is <c>none</c>
+ it is the hashed value of "plain text" i.e. the digest.</d>
+ <v>DigestType = rsa_digest_type() | dsa_digest_type()</v>
+ <v>Key = rsa_public_key() | dsa_public_key()</v>
+ </type>
+ <desc>
+ <p> Creates a digital signature.</p>
+ </desc>
+ </func>
-<!-- <func> -->
-<!-- <name>verify_signature(Digest, Signature, Key) -> </name> -->
-<!-- <name>verify_signature(DerCert, Key, KeyParams) -> </name> -->
-<!-- <name>verify_signature(Digest, Signature, Key, Params) -> Verified </name> -->
-<!-- <fsummary> Verifies the signature. </fsummary> -->
-<!-- <type> -->
-<!-- <v>Digest = binary() </v> -->
-<!-- <v>DerCert = der_bin() </v> -->
-<!-- <v>Signature = binary() </v> -->
-<!-- <v>Key = public_key() </v> -->
-<!-- <v>Params = key_params()</v> -->
-<!-- <v>Verified = boolean()</v> -->
-<!-- </type> -->
-<!-- <desc> -->
-<!-- <p> Verifies the signature Signature. If the key is an rsa-key no -->
-<!-- paramters are neeed.</p> -->
-<!-- </desc> -->
-<!-- </func> -->
+ <func>
+ <name>verify(Msg, DigestType, Signature, Key) -> boolean()</name>
+ <fsummary>Verifies a digital signature.</fsummary>
+ <type>
+ <v>Msg = binary()</v>
+ <d>The msg is either the binary "plain text" data
+ or in the case that digest type is <c>none</c>
+ it is the hashed value of "plain text" i.e. the digest.</d>
+ <v>DigestType = rsa_digest_type() | dsa_digest_type()</v>
+ <v>Signature = binary()</v>
+ <v>Key = rsa_public_key() | dsa_public_key()</v>
+ </type>
+ <desc>
+ <p>Verifies a digital signature</p>
+ </desc>
+ </func>
+
</funcs>
</erlref>