aboutsummaryrefslogtreecommitdiffstats
path: root/lib/public_key/doc/src/public_key.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/public_key/doc/src/public_key.xml')
-rw-r--r--lib/public_key/doc/src/public_key.xml317
1 files changed, 317 insertions, 0 deletions
diff --git a/lib/public_key/doc/src/public_key.xml b/lib/public_key/doc/src/public_key.xml
new file mode 100644
index 0000000000..dc9a96906f
--- /dev/null
+++ b/lib/public_key/doc/src/public_key.xml
@@ -0,0 +1,317 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>2008</year>
+ <year>2008</year>
+ <holder>Ericsson AB, All Rights Reserved</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ The Initial Developer of the Original Code is Ericsson AB.
+ </legalnotice>
+
+ <title>public_key</title>
+ <prepared>Ingela Anderton Andin</prepared>
+ <responsible></responsible>
+ <docno></docno>
+ <date></date>
+ <rev></rev>
+ </header>
+ <module>public_key</module>
+ <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.
+ </p>
+ </description>
+
+ <section>
+ <title>COMMON DATA TYPES </title>
+
+ <note><p>All records used in this manual
+ <!-- except #policy_tree_node{} -->
+ are generated from asn1 specifications
+ and are documented in the User's Guide. See <seealso
+ marker="public_key_records">Public key records</seealso> and <seealso
+ marker="cert_records">X.509 Certificate records</seealso>.
+ </p></note>
+
+ <p>Use the following include directive to get access to the
+ records and constant macros described here and in the User's Guide.</p>
+
+ <code> -include_lib("public_key/include/public_key.hrl"). </code>
+
+ <p><em>Data Types </em></p>
+
+ <p><c>boolean() = true | false</c></p>
+
+ <p><c>string = [bytes()]</c></p>
+
+ <p><c>asn1_der_encoded() = binary() | [bytes()]</c></p>
+
+ <p><c>der_bin() = 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>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>rsa_private_key() = #'RSAPrivateKey'{} </c></p>
+
+ <p><c>dsa_private_key() = #'DSAPrivateKey'{}</c></p>
+
+ <p><c>x509_certificate() = "#Certificate{}"</c></p>
+
+ <p><c>x509_tbs_certificate() = #'TBSCertificate'{} </c></p>
+
+<!-- <p><c>policy_tree() = [Root, Children]</c></p> -->
+
+<!-- <p><c>Root = #policy_tree_node{}</c></p> -->
+
+<!-- <p><c>Children = [] | policy_tree()</c></p> -->
+
+<!-- <p> The policy_tree_node record has the following fields:</p> -->
+
+<!-- <taglist> -->
+
+<!-- <tag>valid_policy</tag> -->
+<!-- <item> Is a single policy OID representing a -->
+<!-- valid policy for the path of length x.</item> -->
+
+<!-- <tag>qualifier_set</tag> -->
+<!-- <item>A set of policy qualifiers associated -->
+<!-- with the valid policy in certificate x.</item> -->
+
+<!-- <tag>critically_indicator</tag> -->
+<!-- <item>The critically_indicator indicates whether the -->
+<!-- certificate policy extension in certificate x was marked as -->
+<!-- critical. </item> -->
+
+<!-- <tag>expected_policy_set</tag> -->
+<!-- <item>The expected_policy_set contains one or more policy OIDs -->
+<!-- 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>
+
+ <func>
+ <name>pem_to_der(File) -> {ok, [Entry]}</name>
+ <fsummary>Reads a PEM file and translates it into its asn1 der
+ encoded parts.</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>
+ </type>
+ <desc>
+ <p>Reads a PEM file and translates it into its asn1 der
+ encoded parts.</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>
+ </type>
+ <desc>
+ <p> Decodes an asn1 encoded pkix certificate.</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_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> -->
+
+<!-- <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, -->
+<!-- [...] -->
+
+<!-- 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> -->
+
+<!-- <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>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>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> -->
+</funcs>
+
+</erlref>